/ Hex Artifact Content
Login

Artifact 472ebb1316087b87e27f13c9465de5e788ae2a66:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20  _IOERR_VNODE    
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29  _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20  _IOERR_AUTH     
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29  _IOERR | (28<<8)
5610: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5620: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5630: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5640: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5660: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5670: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5680: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5690: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56a0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
56b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56c0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56f0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
5700: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5710: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
5730: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5740: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5750: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5760: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5770: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5780: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5790: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57b0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
57c0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57d0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57f0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5800: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5810: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5830: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5850: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5870: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5880: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5890: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
58a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58b0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
58d0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
5900: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
5910: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5930: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5940: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5950: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5980: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59c0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
59d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59e0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a00: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5a10: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5a20: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a50: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a90: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5aa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ab0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5ac0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ad0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5ae0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5af0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b10: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5b30: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b50: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b60: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ba0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5bb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bc0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5be0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c00: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c60: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c70: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c80: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5ca0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5cb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5cc0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ce0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5d00: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5d20: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5d30: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5dc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5de0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5e00: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5e10: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5e20: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e30: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e50: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e60: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e70: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e80: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5ea0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5eb0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5ec0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ed0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5ef0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5f00: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5f30: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f40: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f70: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f80: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5fc0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6000: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6010: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6020: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6030: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6090: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
60a0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
60d0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60e0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6150: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6160: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6190: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
61a0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
61d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61e0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6210: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6220: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6260: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6270: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6280: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6290: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
62b0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
62c0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
62d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6300: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6310: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6320: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6330: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6360: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6380: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50  QLITE_OPEN_FILEP
6390: 52 4f 54 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20  ROTECTION_MASK  
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
63c0: 78 30 30 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65  x00700000../* Re
63d0: 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20  served:         
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63f0: 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f  0x00F00000 */../
6400: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
6410: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
6420: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  stics.**.** The 
6430: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6440: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66  istics method of
6450: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6460: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
6470: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
6480: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
6490: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73  a vector of thes
64a0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
64b0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
64c0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
64d0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
64e0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
64f0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
6500: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
6510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
6520: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
6530: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
6540: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
6550: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
6560: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
6570: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
6580: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6590: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
65a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
65b0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
65c0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
65d0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
65e0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
65f0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
6600: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
6610: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
6620: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
6630: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6640: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6650: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
6660: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
6670: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
6680: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
6690: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
66a0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
66b0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
66c0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
66d0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
66e0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
66f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6700: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
6710: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6720: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
6730: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
6740: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
6750: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
6760: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53  xWrite().  The S
6770: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6780: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6790: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
67a0: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62  hat.** after reb
67b0: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  oot following a 
67c0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c  crash or power l
67d0: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79  oss, the only by
67e0: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65  tes in a.** file
67f0: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74   that were writt
6800: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63  en at the applic
6810: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68  ation level migh
6820: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a  t have changed.*
6830: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63  * and that adjac
6840: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20  ent bytes, even 
6850: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65  bytes within the
6860: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65   same sector are
6870: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74  .** guaranteed t
6880: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20  o be unchanged. 
6890: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
68a0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
68b0: 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20  EN_OPEN.** flag 
68c0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 20  indicate that a 
68d0: 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64  file cannot be d
68e0: 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e  eleted when open
68f0: 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
6900: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6910: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
6920: 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73  that the file is
6930: 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79   on.** read-only
6940: 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f   media and canno
6950: 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65  t be changed eve
6960: 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77  n by processes w
6970: 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20  ith.** elevated 
6980: 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23  privileges..*/.#
6990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
69a0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
69b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
69c0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
69d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
69e0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
69f0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6a10: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6a20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6a30: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6a40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6a50: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6a60: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6a70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6a80: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6a90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6aa0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ab0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6ad0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
6ae0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6af0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
6b00: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
6b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b20: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
6b30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6b40: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
6b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6b60: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
6b70: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
6b80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b90: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
6ba0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6bb0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
6bc0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6bd0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
6be0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
6bf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c00: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6c10: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6c20: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6c30: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6c40: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6c50: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
6c60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
6c70: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
6c80: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6c90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6ca0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
6cb0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
6cc0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
6cd0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6ce0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6cf0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6d00: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6d10: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6d20: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
6d30: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
6d40: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6d50: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
6d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6d70: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
6d80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6d90: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
6da0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
6db0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6dc0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
6dd0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6de0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6df0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6e00: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6e10: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6e20: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
6e30: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
6e40: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
6e50: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
6e60: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
6e70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6e80: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6e90: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
6ea0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
6eb0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6ec0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
6ed0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
6ee0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
6ef0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
6f00: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
6f10: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
6f20: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
6f30: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
6f40: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
6f50: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
6f60: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
6f70: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
6f80: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
6f90: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
6fa0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
6fb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6fc0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
6fd0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
6fe0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
6ff0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
7000: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
7010: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7020: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
7030: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
7040: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
7050: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
7060: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
7070: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
7080: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7090: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
70a0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
70b0: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
70c0: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
70d0: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
70e0: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
70f0: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
7100: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
7110: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
7120: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
7130: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
7140: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
7150: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
7160: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
7170: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
7180: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7190: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
71a0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
71b0: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
71c0: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
71d0: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
71e0: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
71f0: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
7200: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
7210: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
7220: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
7230: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
7240: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
7250: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7260: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
7270: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
7280: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
7290: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
72a0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
72b0: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
72c0: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
72d0: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
72e0: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
72f0: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
7300: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
7310: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
7320: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
7330: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7340: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
7350: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
7360: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
7370: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
7380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7390: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
73a0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
73b0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
73c0: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
73d0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
73e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
73f0: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
7400: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
7410: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
7420: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
7430: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
7440: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
7450: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
7460: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
7470: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
7480: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
7490: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
74a0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
74b0: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
74c0: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
74d0: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
74e0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
74f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7500: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
7510: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
7520: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
7530: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
7540: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
7550: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7560: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
7570: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
7580: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7590: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
75a0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
75b0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
75c0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
75d0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
75e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
75f0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7600: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
7610: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
7620: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
7630: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
7640: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7650: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
7660: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7670: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
7680: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
7690: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
76a0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
76b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
76c0: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
76d0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
76e0: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
76f0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
7700: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
7710: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
7720: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
7730: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
7740: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
7750: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
7760: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7770: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
7780: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7790: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
77a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
77b0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
77c0: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
77d0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
77e0: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
77f0: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
7800: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
7810: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
7820: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7830: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
7840: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
7850: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
7860: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
7870: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
7880: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
7890: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
78a0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
78b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
78c0: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
78d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
78e0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
78f0: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
7900: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
7910: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
7920: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
7930: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7940: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
7950: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
7960: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
7970: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
7980: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
7990: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
79a0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
79b0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
79c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
79d0: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
79e0: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
79f0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
7a00: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
7a10: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
7a20: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
7a30: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
7a40: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
7a50: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
7a60: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7a70: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
7a80: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a90: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
7aa0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7ab0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
7ac0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7ad0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
7ae0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7af0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7b00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7b10: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7b20: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
7b30: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
7b40: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
7b50: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
7b60: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
7b70: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
7b80: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
7b90: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
7ba0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7bb0: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
7bc0: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
7bd0: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
7be0: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
7bf0: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
7c00: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
7c10: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
7c20: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
7c30: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
7c40: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
7c50: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
7c60: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
7c70: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
7c80: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
7c90: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
7ca0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
7cb0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
7cc0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
7cd0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
7ce0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
7cf0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7d00: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
7d10: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
7d20: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
7d30: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
7d40: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
7d50: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
7d60: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
7d70: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
7d80: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
7d90: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7da0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
7db0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
7dc0: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
7dd0: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
7de0: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
7df0: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
7e00: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
7e10: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
7e20: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
7e30: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
7e40: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
7e50: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
7e60: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
7e70: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
7e80: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7e90: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7ea0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7eb0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7ec0: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7ed0: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7ee0: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
7ef0: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
7f00: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
7f10: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65   use..** A [file
7f20: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7f30: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
7f40: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
7f50: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
7f60: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
7f70: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
7f80: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
7f90: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
7fa0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
7fb0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
7fc0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
7fd0: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
7fe0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
7ff0: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
8000: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
8010: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8020: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
8030: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
8040: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
8050: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
8060: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
8070: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
8080: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
8090: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
80a0: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
80b0: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
80c0: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
80d0: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
80e0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
80f0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
8100: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
8110: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
8120: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
8130: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
8140: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
8150: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
8160: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
8170: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
8180: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8190: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
81a0: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
81b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81c0: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
81d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
81e0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
81f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8200: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
8210: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8220: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
8230: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8240: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
8250: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8260: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
8270: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8280: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
8290: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
82a0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
82b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82c0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
82d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82e0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
82f0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
8300: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
8310: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
8320: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8330: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8340: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8350: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8360: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8370: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8380: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8390: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
83a0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
83b0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
83c0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
83d0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
83e0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
83f0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
8400: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8410: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
8420: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8430: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8440: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8450: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8460: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8470: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8480: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8490: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
84a0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
84b0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
84c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
84d0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
84e0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
84f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
8500: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
8510: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
8520: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8530: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8540: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8550: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8560: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8570: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8580: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8590: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
85a0: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
85b0: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
85c0: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
85d0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
85e0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
85f0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8600: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8610: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8620: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8630: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8640: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8650: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8660: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8670: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8680: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8690: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
86a0: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
86b0: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
86c0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
86d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
86e0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
86f0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8700: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8710: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8720: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8730: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8740: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8750: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8760: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8770: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8780: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8790: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
87a0: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
87b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
87c0: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
87d0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
87e0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
87f0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8800: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8820: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8830: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8840: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8850: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8860: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8870: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8880: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8890: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
88a0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
88b0: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
88c0: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
88d0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
88e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
88f0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8900: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8910: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8920: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8930: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8940: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8950: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8960: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8970: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8980: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8990: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
89a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
89b0: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
89c0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
89d0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
89e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
89f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8a00: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8a10: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8a20: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8a30: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8a40: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8a50: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8a60: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8a70: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8a80: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8a90: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8aa0: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8ab0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ac0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8ad0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8ae0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8af0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8b00: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8b10: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8b20: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8b30: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8b40: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8b50: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8b60: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8b70: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
8b80: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
8b90: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
8ba0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8bb0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
8bc0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8bd0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8be0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8bf0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8c00: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8c10: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8c20: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8c30: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8c40: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8c50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8c60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8c70: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
8c80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8c90: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8ca0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8cb0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8cc0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8cd0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8ce0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8cf0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8d00: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8d10: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8d20: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8d30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8d40: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8d50: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8d60: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8d70: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8d80: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8d90: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8da0: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8db0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8dc0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8dd0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8de0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8df0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
8e00: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
8e10: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
8e20: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
8e30: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
8e40: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8e50: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8e60: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
8e70: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8e80: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
8e90: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
8ea0: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
8eb0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
8ec0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
8ed0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
8ee0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
8ef0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
8f00: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
8f10: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
8f20: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8f30: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
8f40: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
8f50: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
8f60: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
8f70: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
8f80: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
8f90: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
8fa0: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
8fb0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
8fc0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
8fd0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
8fe0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
8ff0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9000: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
9010: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9020: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9030: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9040: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9050: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9060: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9070: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9080: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9090: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
90a0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
90b0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
90c0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
90d0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
90e0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
90f0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
9100: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
9110: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
9120: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9130: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9140: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9150: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9160: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9170: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9180: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9190: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
91a0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
91b0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
91c0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
91d0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
91e0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
91f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9200: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
9210: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9220: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9230: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9240: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9250: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9260: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9270: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9280: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9290: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
92a0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
92b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
92c0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
92d0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
92e0: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
92f0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
9300: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9310: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9320: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9330: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9340: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9350: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9360: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9370: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9380: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9390: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
93a0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
93b0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
93c0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
93d0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
93e0: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
93f0: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9400: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9410: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9420: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9430: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9440: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9450: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9460: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9470: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9480: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9490: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
94a0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
94b0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
94c0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
94d0: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
94e0: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
94f0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9500: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9510: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9520: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9530: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9540: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9550: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9560: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9570: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9580: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9590: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
95a0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
95b0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
95c0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
95d0: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
95e0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
95f0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9600: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9610: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9620: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9630: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9640: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9650: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9660: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9670: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9680: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9690: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
96a0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
96b0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
96c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
96d0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
96e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
96f0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9700: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9710: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9720: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9730: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9740: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9750: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9760: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9770: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9780: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9790: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
97a0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
97b0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
97c0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
97d0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
97e0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
97f0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
9800: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
9810: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9820: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9830: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9840: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9850: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
9860: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9870: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9880: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9890: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
98a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
98b0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
98c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
98d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
98e0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
98f0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
9900: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
9910: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
9920: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
9930: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
9940: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
9950: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
9960: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9970: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9980: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
9990: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
99a0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
99b0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
99c0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
99d0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
99e0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
99f0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
9a00: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
9a10: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
9a20: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
9a30: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
9a40: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
9a50: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
9a60: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
9a70: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
9a80: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
9a90: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
9aa0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
9ab0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
9ac0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
9ad0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
9ae0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
9af0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
9b00: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
9b10: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
9b20: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
9b30: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9b40: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
9b50: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
9b60: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
9b70: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
9b80: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
9b90: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
9ba0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
9bb0: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
9bc0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
9bd0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
9be0: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
9bf0: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
9c00: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
9c10: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
9c20: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
9c30: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
9c40: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
9c50: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
9c60: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
9c70: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
9c80: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
9c90: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
9ca0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
9cb0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
9cc0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
9cd0: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
9ce0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9cf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9d00: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
9d10: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9d20: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
9d30: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
9d40: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
9d50: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
9d60: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
9d70: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
9d80: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
9d90: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
9da0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
9db0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9dc0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
9dd0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
9de0: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
9df0: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
9e00: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
9e10: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
9e20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
9e30: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
9e40: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9e50: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
9e60: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
9e70: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
9e80: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
9e90: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
9ea0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
9eb0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
9ec0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
9ed0: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
9ee0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
9ef0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
9f00: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
9f10: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
9f20: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
9f30: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
9f40: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
9f50: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
9f60: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
9f70: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
9f80: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
9f90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9fa0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9fb0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9fc0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9fd0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9fe0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9ff0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a000: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
a010: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a020: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a030: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
a040: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
a050: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a060: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a070: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a080: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
a090: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
a0a0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a0b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a0c0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a0d0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a0e0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a0f0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
a100: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a110: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a120: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
a130: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
a140: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
a150: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
a160: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
a170: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
a180: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
a190: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
a1a0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
a1b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a1c0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
a1d0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a1e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a1f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a200: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a210: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a220: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a230: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a240: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a250: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
a260: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a270: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
a280: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
a290: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a2a0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a2b0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a2c0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
a2d0: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
a2e0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a2f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a300: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
a310: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
a320: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a330: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
a340: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
a350: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
a360: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
a370: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
a380: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
a390: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
a3a0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
a3b0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
a3c0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
a3d0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
a3e0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
a3f0: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
a400: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
a410: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
a420: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a430: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
a440: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a450: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
a460: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
a470: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
a480: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
a490: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
a4a0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
a4b0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
a4c0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
a4d0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
a4e0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
a4f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
a500: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
a510: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
a520: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
a530: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
a540: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
a550: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
a560: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a570: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
a580: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
a590: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
a5a0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
a5b0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
a5c0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
a5d0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
a5e0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
a5f0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
a600: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
a610: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
a620: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
a630: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
a640: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
a650: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
a660: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
a670: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
a680: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
a690: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
a6a0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
a6b0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
a6c0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
a6d0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
a6e0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
a6f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a700: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
a710: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
a720: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
a730: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
a740: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a750: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a760: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
a770: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
a780: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
a790: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
a7a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a7b0: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
a7c0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
a7d0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
a7e0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
a7f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a800: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a810: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
a820: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
a830: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
a840: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
a850: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
a860: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
a870: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
a880: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
a890: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
a8a0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
a8b0: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
a8c0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
a8d0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
a8e0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
a8f0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
a900: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a910: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a920: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
a930: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
a940: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
a950: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
a960: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
a970: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
a980: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
a990: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
a9a0: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
a9b0: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
a9c0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
a9d0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
a9e0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
a9f0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
aa00: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
aa10: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
aa20: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
aa30: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
aa40: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
aa50: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
aa60: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
aa70: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
aa80: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
aa90: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aaa0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
aab0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
aac0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
aad0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
aae0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
aaf0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
ab00: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
ab10: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
ab20: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
ab30: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
ab40: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
ab50: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
ab60: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
ab70: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
ab80: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
ab90: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
aba0: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
abb0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
abc0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
abd0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
abe0: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
abf0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
ac00: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
ac10: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
ac20: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
ac30: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
ac40: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
ac50: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
ac60: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
ac70: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
ac80: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
ac90: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
aca0: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
acb0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
acc0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
acd0: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
ace0: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
acf0: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
ad00: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
ad10: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
ad20: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
ad30: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
ad40: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
ad50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
ad60: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
ad70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ad80: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
ad90: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
ada0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
adb0: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
adc0: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
add0: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
ade0: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
adf0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
ae00: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
ae10: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
ae20: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
ae30: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
ae40: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
ae50: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
ae60: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
ae70: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
ae80: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
ae90: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
aea0: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
aeb0: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
aec0: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
aed0: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
aee0: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
aef0: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
af00: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
af10: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
af20: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
af30: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
af40: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
af50: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
af60: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
af70: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
af80: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
af90: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
afa0: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
afb0: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
afc0: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
afd0: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
afe0: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
aff0: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
b000: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b010: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b020: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
b030: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b040: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b050: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b060: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b070: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b080: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b090: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b0a0: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b0b0: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b0c0: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b0d0: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b0e0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b0f0: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b100: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b110: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b120: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b130: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b140: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b150: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b160: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b170: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b180: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b190: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b1a0: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b1b0: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b1c0: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b1d0: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b1e0: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b1f0: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b200: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b210: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b220: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b230: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b240: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b250: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b260: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b270: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b280: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b290: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b2a0: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b2b0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b2c0: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b2d0: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b2e0: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b2f0: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b300: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b310: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b320: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b330: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b340: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b350: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b360: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b370: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b380: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b390: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b3a0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b3b0: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b3c0: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b3d0: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b3e0: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b3f0: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b400: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b410: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b420: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b430: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b440: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b450: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b460: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b470: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b480: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b490: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b4a0: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b4b0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b4c0: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b4d0: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b4e0: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b4f0: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b500: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b510: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b520: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b530: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b540: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b550: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b560: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b570: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b580: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b590: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b5a0: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b5b0: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b5c0: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b5d0: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b5e0: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
b5f0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
b600: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
b610: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b620: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
b630: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b640: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
b650: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
b660: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
b670: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
b680: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
b690: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
b6a0: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
b6b0: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
b6c0: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
b6d0: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
b6e0: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
b6f0: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
b700: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
b710: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
b720: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b730: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b740: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
b750: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b760: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b770: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
b780: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
b790: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
b7a0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
b7b0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
b7c0: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
b7d0: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
b7e0: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
b7f0: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
b800: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
b810: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
b820: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
b830: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
b840: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
b850: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
b860: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
b870: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b880: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
b890: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
b8a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
b8b0: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
b8c0: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
b8d0: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
b8e0: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
b8f0: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
b900: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
b910: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
b920: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
b930: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
b940: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
b950: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
b960: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
b970: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
b980: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
b990: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
b9a0: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
b9b0: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
b9c0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
b9d0: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
b9e0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
b9f0: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
ba00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
ba10: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
ba20: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
ba30: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
ba40: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
ba50: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
ba60: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
ba70: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
ba80: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
ba90: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
baa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bab0: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
bac0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
bad0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
bae0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
baf0: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
bb00: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
bb10: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
bb20: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
bb30: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
bb40: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
bb50: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
bb60: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
bb70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bb80: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
bb90: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
bba0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bbb0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
bbc0: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
bbd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bbe0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
bbf0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
bc00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bc10: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
bc20: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
bc30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
bc40: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
bc50: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
bc60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
bc70: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
bc80: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
bc90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
bca0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
bcb0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
bcc0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
bcd0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
bce0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
bcf0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
bd00: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
bd10: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
bd20: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
bd30: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
bd40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
bd50: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
bd60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
bd70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bd80: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
bd90: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
bda0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bdb0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
bdc0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
bdd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bde0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
bdf0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
be00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
be10: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
be20: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
be30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
be40: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
be50: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
be60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
be70: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
be80: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
be90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bea0: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
beb0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
bec0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
bed0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
bee0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
bef0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
bf00: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
bf10: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
bf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
bf30: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
bf40: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
bf50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bf60: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
bf70: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
bf80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
bf90: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
bfa0: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
bfb0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bfc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bfd0: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
bfe0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
bff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c000: 32 36 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65  26../* deprecate
c010: 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69  d names */.#defi
c020: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
c030: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c040: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
c050: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c060: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
c070: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c080: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c090: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
c0a0: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
c0b0: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
c0c0: 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54             SQLIT
c0d0: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
c0e0: 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  NO.../*.** CAPI3
c0f0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
c100: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
c110: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
c120: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
c130: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
c140: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
c150: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
c160: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
c170: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
c180: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
c190: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
c1a0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
c1b0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
c1c0: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
c1d0: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
c1e0: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
c1f0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
c200: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
c210: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
c220: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
c230: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
c240: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c250: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
c260: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
c270: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
c280: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
c290: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
c2a0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
c2b0: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
c2c0: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c2d0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
c2e0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
c2f0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
c300: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
c310: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
c320: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
c330: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
c340: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
c350: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
c360: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
c370: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
c380: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
c390: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
c3a0: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
c3b0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c3c0: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
c3d0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
c3e0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
c3f0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
c400: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
c410: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
c420: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
c430: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
c440: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
c450: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
c460: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
c470: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
c480: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
c490: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
c4a0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
c4b0: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
c4c0: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
c4d0: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
c4e0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
c4f0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
c500: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
c510: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
c520: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
c530: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
c540: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
c550: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
c560: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
c570: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
c580: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
c590: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
c5a0: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
c5b0: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
c5c0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c5d0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
c5e0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
c5f0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
c600: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
c610: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
c620: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
c630: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
c640: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
c650: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
c660: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
c670: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
c680: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
c690: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
c6a0: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
c6b0: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
c6c0: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
c6d0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
c6e0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
c6f0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
c700: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
c710: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
c720: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
c730: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
c740: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
c750: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
c760: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
c770: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
c780: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
c790: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
c7a0: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
c7b0: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
c7c0: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
c7d0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
c7e0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
c7f0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
c800: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
c810: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
c820: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
c830: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
c840: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
c850: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
c860: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
c870: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
c880: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
c890: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
c8a0: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
c8b0: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
c8c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
c8d0: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
c8e0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
c8f0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c900: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
c910: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
c920: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
c930: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
c940: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
c950: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
c960: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
c970: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
c980: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
c990: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c9a0: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
c9b0: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
c9c0: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
c9d0: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
c9e0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
c9f0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
ca00: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
ca10: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
ca20: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
ca30: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
ca40: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
ca50: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
ca60: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
ca70: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
ca80: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
ca90: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
caa0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
cab0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
cac0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
cad0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
cae0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
caf0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
cb00: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
cb10: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
cb20: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
cb30: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
cb40: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
cb50: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
cb60: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
cb70: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
cb80: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
cb90: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
cba0: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
cbb0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
cbc0: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
cbd0: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
cbe0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
cbf0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
cc00: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
cc10: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
cc20: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
cc30: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
cc40: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
cc50: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
cc60: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
cc70: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
cc80: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
cc90: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
cca0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
ccb0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
ccc0: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
ccd0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
cce0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
ccf0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
cd00: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
cd10: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
cd20: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
cd30: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
cd40: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
cd50: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
cd60: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
cd70: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
cd80: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
cd90: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
cda0: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
cdb0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
cdc0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
cdd0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
cde0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
cdf0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
ce00: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
ce10: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
ce20: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
ce30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
ce40: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ce50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
ce60: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ce70: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ce80: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
ce90: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
cea0: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
ceb0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cec0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
ced0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cee0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
cef0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cf00: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
cf10: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
cf20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
cf30: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
cf40: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
cf50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
cf60: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
cf70: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
cf80: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
cf90: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
cfa0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
cfb0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
cfc0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
cfd0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
cfe0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
cff0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
d000: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
d010: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
d020: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
d030: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
d040: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
d050: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
d060: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
d070: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
d080: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
d090: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
d0a0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
d0b0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
d0c0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
d0d0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
d0e0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
d0f0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
d100: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
d110: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
d120: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
d130: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
d140: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
d150: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
d160: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
d170: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
d180: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
d190: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
d1a0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d1b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d1c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
d1d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d1e0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
d1f0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
d200: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d210: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
d220: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
d230: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
d240: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
d250: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
d260: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d270: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
d280: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
d290: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
d2a0: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
d2b0: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
d2c0: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
d2d0: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
d2e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d2f0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
d300: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
d310: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
d320: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
d330: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
d340: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
d350: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
d360: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
d370: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
d380: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
d390: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
d3a0: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
d3b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
d3c0: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
d3d0: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
d3e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
d3f0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
d400: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
d410: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
d420: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
d430: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
d440: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
d450: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
d460: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
d470: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
d480: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
d490: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
d4a0: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
d4b0: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
d4c0: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
d4d0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
d4e0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
d4f0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
d500: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
d510: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
d520: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
d530: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
d540: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
d550: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
d560: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
d570: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
d580: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
d590: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
d5a0: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
d5b0: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
d5c0: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
d5d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
d5e0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
d5f0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
d600: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
d610: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
d620: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
d630: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
d640: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
d650: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
d660: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
d670: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
d680: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
d690: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
d6a0: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
d6b0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
d6c0: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
d6d0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
d6e0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
d6f0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
d700: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
d710: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
d720: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
d730: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
d740: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
d750: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
d760: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
d770: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
d780: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
d790: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
d7a0: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
d7b0: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
d7c0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
d7d0: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
d7e0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
d7f0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
d800: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
d810: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
d820: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
d830: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
d840: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
d850: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
d860: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
d870: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
d880: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
d890: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
d8a0: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
d8b0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
d8c0: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
d8d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
d8e0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
d8f0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
d900: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
d910: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
d920: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
d930: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
d940: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
d950: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
d960: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
d970: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
d980: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
d990: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
d9a0: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
d9b0: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
d9c0: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
d9d0: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
d9e0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
d9f0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
da00: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
da10: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
da20: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
da30: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
da40: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
da50: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
da60: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
da70: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
da80: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
da90: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
daa0: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
dab0: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
dac0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
dad0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
dae0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
daf0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
db00: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
db10: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
db20: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
db30: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
db40: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
db50: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
db60: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
db70: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
db80: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
db90: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
dba0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
dbb0: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
dbc0: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
dbd0: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
dbe0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
dbf0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
dc00: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
dc10: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
dc20: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
dc30: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
dc40: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
dc50: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
dc60: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
dc70: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
dc80: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
dc90: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
dca0: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
dcb0: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
dcc0: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
dcd0: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
dce0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
dcf0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
dd00: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
dd10: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
dd20: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
dd30: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
dd40: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
dd50: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
dd60: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
dd70: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
dd80: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
dd90: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
dda0: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
ddb0: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
ddc0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
ddd0: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
dde0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
ddf0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
de00: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
de10: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
de20: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
de30: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
de40: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
de50: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
de60: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
de70: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
de80: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
de90: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
dea0: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
deb0: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
dec0: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
ded0: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
dee0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
def0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
df00: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
df10: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
df20: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
df30: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
df40: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
df50: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
df60: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
df70: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
df80: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
df90: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
dfa0: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
dfb0: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
dfc0: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
dfd0: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
dfe0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
dff0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
e000: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
e010: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
e020: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
e030: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
e040: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
e050: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
e060: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
e070: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
e080: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
e090: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
e0a0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e0b0: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
e0c0: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
e0d0: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
e0e0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
e0f0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
e100: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
e110: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
e120: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
e130: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
e140: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
e150: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
e160: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
e170: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
e180: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
e190: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
e1a0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
e1b0: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
e1c0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
e1d0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
e1e0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
e1f0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
e200: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
e210: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
e220: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
e230: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
e240: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
e250: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
e260: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
e270: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
e280: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
e290: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
e2a0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
e2b0: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
e2c0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
e2d0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
e2e0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
e2f0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
e300: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
e310: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e320: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
e330: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
e340: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
e350: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
e360: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
e370: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
e380: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e390: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
e3a0: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
e3b0: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
e3c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e3d0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
e3e0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
e3f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
e400: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
e410: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e420: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
e430: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
e440: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
e450: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
e460: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e470: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
e480: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
e490: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
e4a0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
e4b0: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
e4c0: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
e4d0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
e4e0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
e4f0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
e500: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
e510: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
e520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
e530: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
e540: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
e550: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e560: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
e570: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e580: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
e590: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
e5a0: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
e5b0: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
e5c0: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
e5d0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
e5e0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
e5f0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
e600: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
e610: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
e620: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e630: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
e640: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
e650: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
e660: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
e670: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
e680: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
e690: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
e6a0: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
e6b0: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
e6c0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
e6d0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
e6e0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
e6f0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e700: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
e710: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
e720: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
e730: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
e740: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
e750: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e760: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e770: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
e780: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
e790: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
e7a0: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
e7b0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e7c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e7d0: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
e7e0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
e7f0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e800: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e810: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
e820: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
e830: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
e840: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
e850: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e860: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
e870: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
e880: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
e890: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
e8a0: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
e8b0: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
e8c0: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
e8d0: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
e8e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
e8f0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
e900: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
e910: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
e920: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
e930: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
e940: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
e950: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
e960: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e970: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
e980: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
e990: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
e9a0: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
e9b0: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
e9c0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
e9d0: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
e9e0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
e9f0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
ea00: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
ea10: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
ea20: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
ea30: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
ea40: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ea50: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
ea60: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ea70: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
ea80: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
ea90: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
eaa0: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
eab0: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
eac0: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
ead0: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
eae0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
eaf0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
eb00: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
eb10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
eb20: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
eb30: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
eb40: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
eb50: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
eb60: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
eb70: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
eb80: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
eb90: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
eba0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
ebb0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
ebc0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
ebd0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ebe0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
ebf0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
ec00: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
ec10: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
ec20: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
ec30: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
ec40: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
ec50: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
ec60: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
ec70: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
ec80: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
ec90: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
eca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
ecb0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
ecc0: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
ecd0: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
ece0: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
ecf0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
ed00: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
ed10: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
ed20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ed30: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
ed40: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
ed50: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
ed60: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
ed70: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
ed80: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
ed90: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
eda0: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
edb0: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
edc0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
edd0: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
ede0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
edf0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
ee00: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
ee10: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
ee20: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
ee30: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ee40: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
ee50: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
ee60: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
ee70: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ee80: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
ee90: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
eea0: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
eeb0: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
eec0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
eed0: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
eee0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
eef0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
ef00: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
ef10: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
ef20: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
ef30: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
ef40: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f  s.** was given o
ef50: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
ef60: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
ef70: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
ef80: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
ef90: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
efa0: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
efb0: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
efc0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
efd0: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
efe0: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
eff0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
f000: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
f010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f020: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
f030: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
f040: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
f050: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
f060: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
f070: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
f080: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f090: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
f0a0: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
f0b0: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
f0c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
f0d0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
f0e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
f0f0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
f100: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
f110: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
f120: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
f130: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
f140: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
f150: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
f160: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
f170: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
f180: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
f190: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
f1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f1b0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
f1c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f1d0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
f1e0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
f1f0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
f200: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
f210: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
f220: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
f230: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
f240: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f250: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
f260: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
f270: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
f280: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
f290: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f2a0: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
f2b0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
f2c0: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
f2d0: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
f2e0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
f2f0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
f300: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
f310: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
f320: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
f330: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
f340: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
f350: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
f360: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
f370: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
f380: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f390: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
f3a0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
f3b0: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
f3c0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
f3d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
f3e0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
f3f0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
f400: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
f410: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
f420: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
f430: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
f440: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
f450: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
f460: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f470: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
f480: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
f490: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f4a0: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
f4b0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
f4c0: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
f4d0: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
f4e0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
f4f0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f500: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
f510: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
f520: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
f530: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
f540: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f550: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
f560: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
f570: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
f580: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
f590: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
f5a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
f5b0: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
f5c0: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
f5d0: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
f5e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f5f0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
f600: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
f610: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f620: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
f630: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
f640: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
f650: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
f660: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
f670: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f680: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
f690: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
f6a0: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
f6b0: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
f6c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f6d0: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
f6e0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
f6f0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
f700: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
f710: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
f720: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
f730: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
f740: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
f750: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
f760: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
f770: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
f780: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
f790: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
f7a0: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
f7b0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
f7c0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
f7d0: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
f7e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
f7f0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
f800: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
f810: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
f820: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
f830: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
f840: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
f850: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
f860: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
f870: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
f880: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
f890: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
f8a0: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
f8b0: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
f8c0: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
f8d0: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
f8e0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
f8f0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
f900: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f910: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
f920: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
f930: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
f940: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
f950: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
f960: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
f970: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
f980: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
f990: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
f9a0: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
f9b0: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
f9c0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
f9d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f9e0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
f9f0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
fa00: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
fa10: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
fa20: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
fa30: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
fa40: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
fa50: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
fa60: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
fa70: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
fa80: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
fa90: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
faa0: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
fab0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
fac0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
fad0: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
fae0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
faf0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
fb00: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
fb10: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
fb20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb30: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
fb40: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
fb50: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
fb60: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
fb70: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
fb80: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
fb90: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
fba0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
fbb0: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
fbc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fbd0: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
fbe0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
fbf0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fc00: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
fc10: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
fc20: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
fc30: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
fc40: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
fc50: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
fc60: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
fc70: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
fc80: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
fc90: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
fca0: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
fcb0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
fcc0: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
fcd0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
fce0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
fcf0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
fd00: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
fd10: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
fd20: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
fd30: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
fd40: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
fd50: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
fd60: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
fd70: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
fd80: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fd90: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
fda0: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
fdb0: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
fdc0: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
fdd0: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
fde0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
fdf0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
fe00: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
fe10: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
fe20: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
fe30: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
fe40: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
fe50: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
fe60: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
fe70: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
fe80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
fe90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
fea0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
feb0: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
fec0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
fed0: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
fee0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
fef0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
ff00: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
ff10: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
ff20: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff30: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
ff40: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
ff50: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ff60: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
ff70: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
ff80: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
ff90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
ffa0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
ffb0: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
ffc0: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
ffd0: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
ffe0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
fff0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
10000 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
10010 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10020 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
10030 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
10040 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
10050 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
10060 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
10070 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
10080 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
10090 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
100a0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
100b0 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
100c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
100d0 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
100e0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
100f0 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
10100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
10110 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
10120 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
10130 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
10140 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
10150 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
10160 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
10170 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
10180 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10190 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
101a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
101b0 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
101c0 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
101d0 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
101e0 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
101f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
10200 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
10210 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
10220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
10230 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
10240 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
10250 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
10260 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
10270 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
10280 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
10290 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
102a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
102b0 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
102c0 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
102d0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
102e0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
102f0 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
10300 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
10310 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
10320 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
10330 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
10340 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
10350 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
10360 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
10370 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
10380 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
10390 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
103a0 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
103b0 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
103c0 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
103d0 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
103e0 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69  *.** <b>The sqli
103f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10400 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
10410 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70  readsafe. The ap
10420 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
10430 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t ensure that no
10440 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
10450 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
10460 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
10470 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
10480 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10490 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a  is running.</b>.
104a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
104b0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
104c0 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  face.** may only
104d0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
104e0 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
104f0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
10500 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
10510 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
10520 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
10530 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10540 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
10550 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10560 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
10570 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10580 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
10590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
105a0 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
105b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
105c0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
105d0 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
105e0 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
105f0 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
10600 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
10610 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
10620 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
10630 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
10640 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10650 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
10660 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10670 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10680 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
10690 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
106a0 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
106b0 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
106c0 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
106d0 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
106e0 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
106f0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10700 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10710 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10720 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10730 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10740 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
10750 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10760 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10770 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10780 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
10790 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
107a0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
107b0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
107c0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
107d0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
107e0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
107f0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10800 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10810 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10820 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
10830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10840 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
10850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10860 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
10870 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
10880 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10890 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
108a0 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
108b0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
108c0 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
108d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
108e0 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
108f0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
10900 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10910 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
10920 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
10930 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
10940 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
10950 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
10960 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
10970 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
10980 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
10990 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
109a0 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
109b0 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
109c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
109d0 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
109e0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
109f0 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
10a00 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
10a10 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
10a20 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
10a30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
10a40 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
10a50 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
10a60 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
10a70 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10a80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
10a90 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
10aa0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
10ab0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
10ac0 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
10ad0 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
10ae0 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
10af0 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
10b00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
10b10 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
10b20 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
10b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10b40 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
10b50 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
10b60 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
10b70 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
10b80 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
10b90 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
10ba0 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
10bb0 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
10bc0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
10bd0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
10be0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
10bf0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
10c00 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
10c10 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
10c20 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
10c30 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
10c40 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
10c50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10c60 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
10c70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10c80 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
10c90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10ca0 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
10cb0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
10cc0 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
10cd0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
10ce0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
10cf0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
10d00 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
10d10 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
10d20 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
10d30 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
10d40 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
10d50 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
10d60 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
10d70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10d80 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
10d90 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
10da0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
10db0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
10dc0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
10dd0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
10de0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
10df0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
10e00 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
10e10 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
10e20 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
10e30 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
10e40 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
10e50 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
10e60 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
10e70 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
10e80 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
10e90 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
10ea0 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
10eb0 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
10ec0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
10ed0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
10ee0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
10ef0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
10f00 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
10f10 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
10f20 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
10f30 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
10f40 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
10f50 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
10f60 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
10f70 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
10f80 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
10f90 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
10fa0 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
10fb0 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
10fc0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
10fd0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
10fe0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
10ff0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
11000 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
11010 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
11020 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
11030 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
11040 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
11050 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
11060 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
11070 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11080 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
11090 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
110a0 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
110b0 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
110c0 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
110d0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
110e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
110f0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
11100 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
11110 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
11120 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
11130 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
11140 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
11150 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
11160 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
11170 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
11180 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
11190 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
111a0 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
111b0 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
111c0 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
111d0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
111e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
111f0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
11200 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
11210 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
11220 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
11230 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
11240 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
11250 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
11260 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
11270 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
11280 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
11290 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
112a0 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
112b0 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
112c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
112d0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
112e0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
112f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
11300 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
11310 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
11320 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
11330 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
11340 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
11350 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
11360 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
11370 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
11380 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
11390 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
113a0 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
113b0 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
113c0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
113d0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
113e0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
113f0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
11400 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
11410 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
11420 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
11430 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
11440 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
11450 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11460 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
11470 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
11480 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
11490 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
114a0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
114b0 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
114c0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
114d0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
114e0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
114f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
11500 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11510 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
11520 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
11530 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
11540 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
11550 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
11560 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
11570 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
11580 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
11590 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
115a0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
115b0 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
115c0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
115d0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
115e0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
115f0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
11600 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
11610 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
11620 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
11630 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
11640 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
11650 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11660 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
11670 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
11680 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
11690 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
116a0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
116b0 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
116c0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
116d0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
116e0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
116f0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
11700 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
11710 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
11720 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
11730 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
11740 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
11750 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
11760 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
11770 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
11780 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
11790 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
117a0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
117b0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
117c0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
117d0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
117e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
117f0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
11800 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
11810 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
11820 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
11830 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
11840 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
11850 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
11860 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
11870 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
11880 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11890 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
118a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
118b0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
118c0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
118d0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
118e0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
118f0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
11900 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
11910 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
11920 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
11930 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
11940 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
11950 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
11960 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
11970 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
11980 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
11990 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
119a0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
119b0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
119c0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
119d0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
119e0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
119f0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
11a00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
11a10 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
11a20 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
11a30 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
11a40 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
11a50 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
11a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11a70 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
11a80 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
11a90 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
11aa0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
11ab0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
11ac0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
11ad0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
11ae0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11af0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
11b00 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
11b10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
11b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
11b30 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11b40 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
11b50 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11b60 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
11b70 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
11b80 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
11b90 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
11ba0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11bb0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
11bc0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
11bd0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
11be0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
11bf0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
11c00 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
11c10 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
11c20 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
11c30 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
11c40 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11c50 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
11c60 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
11c70 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
11c80 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
11c90 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
11ca0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11cb0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
11cc0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
11cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11ce0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
11cf0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
11d00 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
11d10 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11d20 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11d30 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11d40 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11d50 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11d60 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
11d70 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
11d80 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
11d90 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
11da0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
11db0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
11dc0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
11dd0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
11de0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
11df0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
11e00 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11e10 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11e20 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11e30 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11e40 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11e50 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11e60 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11e70 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
11e80 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
11e90 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
11ea0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
11eb0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
11ec0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
11ed0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11ee0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
11ef0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11f00 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
11f10 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
11f20 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
11f30 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11f40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11f50 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
11f60 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
11f70 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
11f80 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
11f90 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
11fa0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
11fb0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
11fc0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
11fd0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
11fe0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
11ff0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
12000 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
12010 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
12020 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12030 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12040 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12050 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
12060 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
12070 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
12080 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
12090 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
120a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
120b0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
120c0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
120d0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
120e0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
120f0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
12100 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
12110 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
12120 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
12130 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
12140 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
12150 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
12160 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
12170 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
12180 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
12190 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
121a0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
121b0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
121c0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
121d0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
121e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
121f0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12200 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
12210 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
12220 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
12230 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12240 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12250 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12260 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12270 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12290 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
122a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
122b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
122c0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
122d0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
122e0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
122f0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
12300 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
12310 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
12320 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
12330 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12340 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12350 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
12360 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12370 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
12380 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
12390 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
123a0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
123b0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
123c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
123d0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
123e0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
123f0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
12400 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
12410 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
12420 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12430 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
12440 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
12450 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
12460 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
12470 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
12480 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
12490 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
124a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
124b0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
124c0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
124d0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
124e0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
124f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
12500 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
12510 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12520 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
12530 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
12540 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
12550 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12560 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12570 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12580 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12590 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
125a0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
125b0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
125c0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
125d0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
125e0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
125f0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
12600 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12610 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
12620 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12630 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
12640 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12650 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
12660 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12670 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12680 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
12690 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
126a0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
126b0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
126c0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
126d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
126e0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
126f0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
12700 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12710 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12720 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12730 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
12740 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
12750 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
12760 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
12770 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12780 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12790 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
127a0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
127b0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
127c0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
127d0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
127e0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
127f0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
12800 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
12810 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
12820 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12830 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
12840 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12850 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
12860 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12880 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
12890 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
128a0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
128b0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
128c0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
128d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
128e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
128f0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
12900 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
12910 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12920 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12930 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
12940 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
12950 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12960 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12970 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12980 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
12990 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
129a0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
129b0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
129c0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
129d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
129e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
129f0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
12a00 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
12a10 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
12a20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
12a30 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
12a40 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
12a50 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
12a60 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12a70 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12a80 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
12a90 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12aa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12ab0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12ac0 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
12ad0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
12ae0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
12af0 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
12b00 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
12b10 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
12b20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
12b30 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
12b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12b50 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
12b60 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
12b70 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12b80 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
12b90 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
12ba0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
12bb0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12bc0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12bd0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12be0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12bf0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12c00 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12c10 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12c20 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12c30 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12c40 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12c50 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12c60 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
12c70 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
12c80 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12c90 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
12ca0 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
12cb0 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12cc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12cd0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12ce0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12cf0 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12d00 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12d10 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12d20 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12d30 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
12d40 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12d50 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
12d60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12d70 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
12d80 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
12d90 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
12da0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12db0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12dc0 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12dd0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
12de0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
12df0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
12e00 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
12e10 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12e20 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
12e30 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
12e40 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
12e50 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
12e60 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
12e70 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
12e80 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
12e90 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
12ea0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
12eb0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
12ec0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
12ed0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
12ee0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
12ef0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12f00 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12f10 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
12f20 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
12f30 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
12f40 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12f50 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
12f60 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
12f70 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
12f80 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
12f90 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
12fa0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
12fb0 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
12fc0 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
12fd0 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
12fe0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
12ff0 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
13000 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
13010 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
13020 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
13030 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
13040 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
13050 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
13060 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
13070 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
13080 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
13090 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
130a0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
130b0 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
130c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
130d0 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
130e0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
130f0 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
13100 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13110 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
13120 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
13130 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
13140 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
13150 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
13160 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
13170 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
13180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13190 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
131a0 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
131b0 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
131c0 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
131d0 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
131e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
131f0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
13200 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13210 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
13220 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13240 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
13250 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13260 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13270 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13280 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
13290 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
132a0 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
132b0 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
132c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
132d0 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
132e0 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
132f0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
13300 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13310 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
13320 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13330 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
13340 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
13350 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a  CONFIG_PCACHE2].
13360 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13370 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65   option..** ^The
13380 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13390 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
133a0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
133b0 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
133c0 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
133d0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
133e0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
133f0 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
13400 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
13410 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
13420 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
13430 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
13440 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
13450 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
13460 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
13470 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
13480 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
13490 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
134a0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
134b0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
134c0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
134d0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
134e0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
134f0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
13500 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ned using the [S
13510 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13520 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f  CHE_HDRSZ] optio
13530 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  n .** to [sqlite
13540 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20  3_config()]..** 
13550 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13560 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13570 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13580 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
13590 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
135a0 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
135b0 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
135c0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
135d0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  d pointer to an 
135e0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
135f0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74  lock of memory t
13600 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61  hat.** is at lea
13610 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
13620 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69   memory, otherwi
13630 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  se subsequent be
13640 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
13650 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69  efined..** ^SQLi
13660 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
13670 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
13680 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
13690 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
136a0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
136b0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
136c0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
136d0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
136e0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
136f0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
13700 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
13710 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
13720 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13730 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
13740 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13750 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13760 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
13770 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
13780 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
13790 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
137a0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
137b0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
137c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
137d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
137e0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
137f0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
13800 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
13810 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
13820 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13830 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13840 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13850 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
13860 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
13870 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
13880 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
13890 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
138a0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
138b0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
138c0 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
138d0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
138e0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
138f0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
13900 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
13910 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
13920 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13930 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
13940 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
13950 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
13960 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
13970 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13980 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
139a0 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
139b0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
139c0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
139d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
139e0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
139f0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
13a00 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13a10 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
13a20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
13a30 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13a40 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13a50 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
13a60 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
13a70 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
13a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13a90 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
13aa0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
13ab0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13ac0 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13ad0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13ae0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
13af0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
13b00 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
13b10 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
13b20 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13b30 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13b40 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13b50 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
13b60 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
13b70 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
13b80 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
13b90 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
13ba0 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
13bb0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13bc0 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
13bd0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
13be0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
13bf0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13c00 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13c10 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13c20 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13c30 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13c40 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13c50 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13c60 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
13c70 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
13c80 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
13c90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13ca0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13cb0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
13cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13cd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13ce0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13cf0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13d00 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
13d10 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
13d20 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13d30 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13d40 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13d50 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13d60 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
13d70 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13d80 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
13d90 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
13da0 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
13db0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
13dc0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13dd0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13de0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
13df0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
13e00 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13e10 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13e20 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
13e30 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13e40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
13e50 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
13e60 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13e70 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13e80 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13e90 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13ea0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13eb0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13ec0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13ed0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13ee0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13ef0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13f00 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13f10 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13f20 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13f30 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
13f40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13f50 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
13f60 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
13f70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13f80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
13f90 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
13fa0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13fb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13fc0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13fd0 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
13fe0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13ff0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
14000 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
14010 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14020 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14030 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14040 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
14050 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14060 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
14070 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
14080 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
14090 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
140a0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
140b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
140c0 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
140d0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
140e0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
140f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
14100 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
14110 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
14120 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
14130 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
14140 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
14150 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
14160 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14170 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14180 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14190 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
141a0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
141b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
141c0 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
141d0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
141e0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
141f0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
14200 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
14210 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14220 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
14230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14240 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
14250 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14260 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14270 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14280 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14290 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
142a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
142b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
142c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
142d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
142e0 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
142f0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
14300 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
14310 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
14320 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
14330 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
14340 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
14350 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
14360 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14370 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
14380 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
14390 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
143a0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
143b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
143c0 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
143d0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
143e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
143f0 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
14400 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
14410 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
14420 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
14430 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
14440 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
14450 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
14460 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
14470 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
14480 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
14490 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
144a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
144b0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
144c0 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
144d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
144e0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
144f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14500 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
14510 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14530 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
14540 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14550 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
14560 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14570 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14580 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14590 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
145a0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
145b0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
145c0 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
145d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
145e0 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
145f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
14600 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
14610 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14620 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
14630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14640 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
14650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14660 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
14670 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14680 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14690 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
146a0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
146b0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
146c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
146d0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
146e0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
146f0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
14700 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
14710 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
14720 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
14730 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
14740 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14760 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14770 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
14780 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14790 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
147a0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
147b0 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
147c0 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
147d0 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
147e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
147f0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
14800 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
14810 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
14820 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
14830 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
14840 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
14850 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
14860 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
14870 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
14880 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
14890 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
148a0 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
148b0 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
148c0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
148d0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
148e0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
148f0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
14900 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
14910 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
14920 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
14930 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
14940 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
14950 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
14960 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14970 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14980 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
14990 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
149a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
149b0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
149c0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
149d0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
149e0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
149f0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
14a00 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
14a10 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
14a20 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14a30 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
14a40 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14a50 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
14a60 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
14a70 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
14a80 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
14a90 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
14aa0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
14ab0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14ac0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14ad0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14ae0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14af0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14b00 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14b10 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14b20 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
14b30 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
14b40 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
14b50 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
14b60 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
14b70 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
14b80 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
14b90 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
14ba0 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
14bb0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14bc0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14bd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14be0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14bf0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14c00 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14c10 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14c20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14c30 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
14c40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14c50 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
14c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c70 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
14c80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14c90 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
14ca0 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
14cb0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14cc0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14cd0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
14ce0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
14cf0 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
14d00 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14d10 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
14d20 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
14d30 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
14d40 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14d50 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
14d60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
14d70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
14d80 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
14d90 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14da0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14db0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14dc0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14dd0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14de0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14df0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14e00 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14e10 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14e20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14e30 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14e40 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14e50 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14e60 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14e70 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14e80 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14e90 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14ea0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14eb0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14ec0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14ed0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14ee0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14ef0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
14f00 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14f10 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14f20 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
14f30 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
14f40 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
14f50 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
14f60 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
14f70 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
14f80 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14f90 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
14fa0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14fb0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14fc0 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14fd0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14fe0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14ff0 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
15000 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
15010 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
15020 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
15030 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
15040 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
15050 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
15060 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
15070 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
15080 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
15090 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
150a0 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
150b0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
150c0 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
150d0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
150e0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
150f0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
15100 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15110 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
15120 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
15130 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
15140 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
15150 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
15160 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
15170 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15180 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15190 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
151a0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
151b0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
151c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
151d0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
151e0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
151f0 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
15200 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
15210 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
15220 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
15230 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
15240 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
15250 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
15260 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
15270 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
15280 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
15290 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
152a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
152b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
152c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
152d0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
152e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
152f0 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
15300 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15310 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
15320 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
15330 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
15340 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
15350 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
15360 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
15370 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
15380 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
15390 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
153a0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
153b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
153c0 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
153d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
153e0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
153f0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
15400 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
15410 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15420 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15430 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
15440 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15450 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
15460 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15470 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
15480 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
15490 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
154a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
154b0 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
154c0 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
154d0 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
154e0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
154f0 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
15500 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
15510 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
15520 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
15530 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
15540 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
15550 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
15560 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15570 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
15580 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15590 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
155a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
155b0 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
155c0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
155d0 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
155e0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
155f0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
15600 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
15610 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
15620 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
15630 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
15640 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
15650 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15660 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
15670 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
15680 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15690 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
156a0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
156b0 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
156c0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
156d0 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
156e0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
156f0 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
15700 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15710 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
15720 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
15730 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
15740 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
15750 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
15760 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
15770 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
15780 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
15790 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
157a0 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
157b0 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
157c0 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
157d0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
157e0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
157f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15800 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
15810 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15820 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
15830 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
15840 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
15850 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
15860 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
15870 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
15880 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
15890 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
158a0 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
158b0 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
158c0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
158d0 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
158e0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
158f0 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
15900 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15910 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
15920 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
15930 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15940 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
15950 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
15960 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
15970 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
15980 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
15990 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
159a0 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
159b0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
159c0 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
159d0 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
159e0 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
159f0 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
15a00 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
15a10 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
15a20 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15a30 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15a40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
15a50 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
15a60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15a70 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
15a80 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
15a90 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
15aa0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
15ab0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15ac0 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15ad0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15ae0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15af0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15b00 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15b10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15b20 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15b30 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15b40 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15b50 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
15b60 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15b70 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
15b80 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
15b90 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
15ba0 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
15bb0 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
15bc0 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
15bd0 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
15be0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15bf0 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15c00 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15c10 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15c20 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15c30 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15c40 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15c50 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15c60 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15c70 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
15c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15c90 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
15ca0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15cb0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
15cc0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15cd0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15ce0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
15cf0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15d00 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
15d10 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
15d20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
15d30 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
15d40 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
15d50 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
15d60 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15d70 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
15d80 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
15d90 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
15da0 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
15db0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
15dc0 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
15dd0 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
15de0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
15df0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15e00 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
15e10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15e20 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
15e30 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15e40 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
15e50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15e60 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15e70 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
15e80 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
15e90 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
15ea0 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
15eb0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
15ec0 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
15ed0 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
15ee0 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
15ef0 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
15f00 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
15f10 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
15f20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15f30 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
15f40 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
15f50 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
15f60 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
15f70 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
15f80 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
15f90 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
15fa0 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
15fb0 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
15fc0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
15fd0 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
15fe0 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
15ff0 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
16000 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
16010 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
16020 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
16030 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
16040 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ue..** </dl>.*/.
16050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16060 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
16070 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
16080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16090 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
160a0 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
160b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
160c0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
160d0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
160e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
160f0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
16100 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
16110 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
16120 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16130 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
16140 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
16150 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16160 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16170 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16180 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
16190 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
161a0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
161b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
161c0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
161d0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
161e0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
161f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16200 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
16210 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16220 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
16230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16240 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16250 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
16260 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
16270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16280 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
16290 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
162a0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
162b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
162c0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
162d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
162e0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
162f0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
16300 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
16310 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
16320 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
16330 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
16340 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16350 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
16360 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16380 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
16390 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
163a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
163b0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
163c0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
163d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
163e0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
163f0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
16400 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16410 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16420 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
16430 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16440 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16450 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
16460 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
16470 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
16480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16490 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
164a0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
164b0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
164c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
164d0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
164e0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
164f0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
16500 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16510 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
16520 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
16530 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16540 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16550 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
16560 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
16570 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
16580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16590 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
165a0 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
165b0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
165c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
165d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
165e0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
165f0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
16600 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16610 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
16620 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
16630 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
16640 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
16650 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
16660 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
16670 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
16680 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
16690 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
166a0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
166b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
166c0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
166d0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
166e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
166f0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
16700 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
16710 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
16720 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
16730 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
16740 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
16750 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
16760 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
16770 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16780 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
16790 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
167a0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
167b0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
167c0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
167d0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
167e0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
167f0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
16800 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
16810 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
16820 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
16830 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
16840 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
16850 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
16860 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
16870 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
16880 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
16890 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
168a0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
168b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
168c0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
168d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
168e0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
168f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16900 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
16910 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
16920 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
16930 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
16940 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
16950 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16960 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
16970 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
16980 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
16990 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
169a0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
169b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
169c0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
169d0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
169e0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
169f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16a00 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
16a10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16a20 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
16a30 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
16a40 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
16a50 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
16a60 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
16a70 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
16a80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
16a90 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
16aa0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
16ab0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
16ac0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
16ad0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
16ae0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
16af0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
16b00 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
16b10 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
16b20 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
16b30 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
16b40 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
16b50 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
16b60 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
16b70 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
16b80 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
16b90 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
16ba0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
16bb0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
16bc0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
16bd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
16be0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16bf0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
16c00 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
16c10 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
16c20 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
16c30 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
16c40 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
16c50 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
16c60 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
16c70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16c80 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16c90 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
16ca0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
16cb0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
16cc0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
16cd0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
16ce0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
16cf0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
16d00 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
16d10 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
16d20 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
16d30 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
16d40 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
16d50 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
16d60 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
16d70 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16d80 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16d90 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
16da0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
16db0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
16dc0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
16dd0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
16de0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
16df0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
16e00 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
16e10 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16e20 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16e30 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
16e40 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16e50 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
16e60 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
16e70 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16e80 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16e90 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
16ea0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16eb0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16ec0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16ed0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16ee0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16ef0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16f00 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
16f10 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
16f20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
16f30 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
16f40 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
16f50 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
16f60 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
16f70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16f80 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16f90 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16fa0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16fb0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16fc0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16fd0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
16fe0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
16ff0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17000 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17010 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17020 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17030 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17040 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17050 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17060 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17070 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17080 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17090 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
170a0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
170b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
170c0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
170d0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
170e0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
170f0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
17100 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17110 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17120 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17130 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17140 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17150 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17160 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17170 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17180 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17190 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
171a0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
171b0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
171c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
171d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
171e0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
171f0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17200 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17210 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
17220 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17230 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17240 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17250 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17260 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17280 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17290 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
172a0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
172b0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
172c0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
172d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
172e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
172f0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
17300 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
17310 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17320 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17330 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
17340 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
17350 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17360 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17370 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
17380 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
17390 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
173a0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
173b0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
173c0 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
173d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
173e0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
173f0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
17400 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
17410 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
17420 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
17430 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
17440 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
17450 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
17460 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
17470 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
17480 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
17490 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
174a0 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
174b0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
174c0 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
174d0 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
174e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
174f0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
17500 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
17510 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
17520 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
17530 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
17540 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
17550 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
17560 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
17570 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
17580 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
17590 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
175a0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
175b0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
175c0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
175d0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
175e0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
175f0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
17600 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
17610 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
17620 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
17630 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
17640 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
17650 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
17660 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
17670 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
17680 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
17690 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
176a0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
176b0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
176c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
176d0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
176e0 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
176f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
17700 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
17710 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
17720 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17730 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
17740 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
17750 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
17760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17770 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
17780 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
17790 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
177a0 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
177b0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
177c0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
177d0 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
177e0 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
177f0 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
17800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17810 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
17820 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17830 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
17840 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
17850 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
17860 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
17870 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
17880 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
17890 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
178a0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
178b0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
178c0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
178d0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
178e0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
178f0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
17900 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
17910 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
17920 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
17930 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
17940 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
17950 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17960 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
17970 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
17980 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
17990 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
179a0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
179b0 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
179c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
179d0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
179e0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
179f0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
17a00 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
17a10 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
17a20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
17a30 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
17a40 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
17a50 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
17a60 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
17a70 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
17a80 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
17a90 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
17aa0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
17ab0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
17ac0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
17ad0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
17ae0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
17af0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
17b00 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
17b10 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
17b20 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
17b30 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17b40 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
17b50 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
17b60 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
17b70 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
17b80 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
17b90 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
17ba0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
17bb0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
17bc0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
17bd0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
17be0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
17bf0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
17c00 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
17c10 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
17c20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
17c30 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
17c40 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
17c50 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
17c60 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
17c70 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
17c80 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
17c90 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
17ca0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
17cb0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
17cc0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
17cd0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
17ce0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
17cf0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
17d00 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
17d10 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
17d20 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
17d30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
17d40 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
17d50 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17d60 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
17d70 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
17d80 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
17d90 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
17da0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
17db0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17dc0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
17dd0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17de0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
17df0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
17e00 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
17e10 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
17e20 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
17e30 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
17e40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
17e50 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17e60 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
17e70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17e80 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
17e90 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
17ea0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
17eb0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
17ec0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
17ed0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
17ee0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
17ef0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
17f00 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
17f10 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
17f20 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
17f30 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
17f40 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
17f50 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
17f60 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
17f70 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
17f80 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
17f90 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
17fa0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
17fb0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
17fc0 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
17fd0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
17fe0 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
17ff0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
18000 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
18010 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
18020 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18030 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
18040 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
18050 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
18060 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
18070 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
18080 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
18090 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
180a0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
180b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
180c0 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
180d0 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
180e0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
180f0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
18100 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
18110 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
18120 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
18130 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
18140 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
18150 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
18160 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
18170 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
18180 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
18190 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
181a0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
181b0 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
181c0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
181d0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
181e0 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
181f0 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
18200 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
18210 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
18220 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
18230 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
18240 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
18250 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
18260 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
18270 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
18280 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
18290 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
182a0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
182b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
182c0 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
182d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
182e0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
182f0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
18300 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
18310 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
18320 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
18330 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
18340 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
18350 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18360 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
18370 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18380 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
18390 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
183a0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
183b0 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
183c0 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
183d0 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
183e0 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
183f0 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
18400 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
18410 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
18420 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
18430 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
18440 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
18450 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
18460 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18470 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
18480 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
18490 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
184a0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
184b0 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
184c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
184d0 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
184e0 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
184f0 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
18500 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
18510 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
18520 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
18530 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
18540 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
18550 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
18560 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
18570 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
18580 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
18590 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
185a0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
185b0 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
185c0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
185d0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
185e0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
185f0 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
18600 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
18610 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
18620 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
18630 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
18640 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
18650 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
18660 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
18670 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
18680 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
18690 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
186a0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
186b0 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
186c0 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
186d0 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
186e0 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
186f0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
18700 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
18710 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
18720 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
18730 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
18740 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
18750 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
18760 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
18770 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
18780 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
18790 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
187a0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
187b0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
187c0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
187d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
187e0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
187f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
18800 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
18810 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18820 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
18830 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
18840 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
18850 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
18860 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
18870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
18880 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
18890 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
188a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
188b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
188c0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
188d0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
188e0 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
188f0 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
18900 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
18910 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
18920 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
18930 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
18940 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
18950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18960 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
18970 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
18980 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
18990 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
189a0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
189b0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
189c0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
189d0 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
189e0 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
189f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
18a00 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18a10 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
18a20 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
18a30 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
18a40 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
18a50 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
18a60 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
18a70 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
18a80 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
18a90 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
18aa0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
18ab0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
18ac0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
18ad0 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
18ae0 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
18af0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
18b00 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
18b10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
18b20 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
18b30 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
18b40 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
18b50 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
18b60 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
18b70 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
18b80 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
18b90 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
18ba0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
18bb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18bc0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
18bd0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18be0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
18bf0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
18c00 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
18c10 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18c20 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
18c30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18c40 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
18c50 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
18c60 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
18c70 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
18c80 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
18c90 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18ca0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
18cb0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
18cc0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
18cd0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
18ce0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
18cf0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
18d00 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
18d10 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
18d20 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
18d30 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
18d40 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
18d50 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
18d60 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
18d70 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
18d80 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
18d90 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
18da0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
18db0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
18dc0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
18dd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
18de0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
18df0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
18e00 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
18e10 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
18e20 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
18e30 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
18e40 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
18e50 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
18e60 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
18e70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18e80 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
18e90 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
18ea0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
18eb0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18ec0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
18ed0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
18ee0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
18ef0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
18f00 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
18f10 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18f20 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
18f30 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
18f40 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
18f50 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
18f60 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
18f70 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
18f80 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
18f90 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
18fa0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
18fb0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
18fc0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
18fd0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
18fe0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
18ff0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
19000 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
19010 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
19020 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
19030 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
19040 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
19050 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
19060 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
19070 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
19080 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
19090 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
190a0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
190b0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
190c0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
190d0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
190e0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
190f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19100 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
19110 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
19120 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
19130 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
19140 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
19150 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
19160 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
19170 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
19180 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
19190 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
191a0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
191b0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
191c0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
191d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
191e0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
191f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
19200 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
19210 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
19220 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
19230 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
19240 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
19250 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
19260 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
19270 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
19280 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19290 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
192a0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
192b0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
192c0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
192d0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
192e0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
192f0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
19300 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
19310 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
19320 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
19330 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
19340 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
19350 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
19360 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
19370 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
19380 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
19390 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
193a0 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
193b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
193c0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
193d0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
193e0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
193f0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
19400 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
19410 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19420 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
19430 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
19440 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
19450 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
19460 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
19470 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
19480 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
19490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
194a0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
194b0 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
194c0 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
194d0 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
194e0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
194f0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
19500 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
19510 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
19520 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
19530 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
19540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
19550 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
19560 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
19570 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
19580 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
19590 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
195a0 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
195b0 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
195c0 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
195d0 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
195e0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
195f0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
19600 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
19610 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
19620 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
19630 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
19640 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
19650 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
19660 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
19670 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
19680 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
19690 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
196a0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
196b0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
196c0 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
196d0 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
196e0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
196f0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
19700 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
19710 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
19720 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
19730 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
19740 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
19750 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
19760 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
19770 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
19780 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
19790 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
197a0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
197b0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
197c0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
197d0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
197e0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
197f0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
19800 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
19810 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
19820 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
19830 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
19840 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
19850 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
19860 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19870 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
19880 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
19890 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
198a0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
198b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
198c0 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
198d0 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
198e0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
198f0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
19900 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19910 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
19920 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
19930 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
19940 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
19950 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
19960 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
19970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
19980 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
19990 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
199a0 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
199b0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
199c0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
199d0 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
199e0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
199f0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
19a00 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
19a10 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
19a20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
19a30 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
19a40 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
19a50 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
19a60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
19a70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19a80 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
19a90 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
19aa0 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
19ab0 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
19ac0 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61  {busy-handler ca
19ad0 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61  llback} {busy ha
19ae0 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  ndler}.** METHOD
19af0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19b00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73  ^The sqlite3_bus
19b10 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29  y_handler(D,X,P)
19b20 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
19b30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19b40 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68  n X.** that migh
19b50 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
19b60 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
19b70 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
19b80 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61  mpt is made to a
19b90 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65  ccess a database
19ba0 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65   table associate
19bb0 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62  d with.** [datab
19bc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19bd0 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74  D when another t
19be0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
19bf0 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c  ess has the tabl
19c00 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65  e locked..** The
19c10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19c20 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63  ndler() interfac
19c30 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70  e is used to imp
19c40 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74  lement.** [sqlit
19c50 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
19c60 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62  )] and [PRAGMA b
19c70 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a  usy_timeout]..**
19c80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
19c90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
19ca0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
19cb0 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75  BUSY].** is retu
19cc0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
19cd0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
19ce0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
19cf0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
19d00 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
19d10 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
19d20 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
19d30 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
19d40 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
19d50 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
19d60 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
19d70 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
19d80 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
19d90 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
19da0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
19db0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
19dc0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
19dd0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
19de0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
19df0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
19e00 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
19e10 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
19e20 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
19e30 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
19e40 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75   invoked previou
19e50 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65  sly for the same
19e60 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
19e70 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
19e80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19e90 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
19ea0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
19eb0 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
19ec0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
19ed0 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
19ee0 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65  BUSY] is returne
19ef0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  d.** to the appl
19f00 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  ication..** ^If 
19f10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
19f20 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
19f30 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
19f40 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
19f50 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
19f60 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79  abase and the cy
19f70 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
19f80 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
19f90 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
19fa0 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
19fb0 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
19fc0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
19fd0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
19fe0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
19ff0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1a000 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1a010 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1a020 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1a030 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1a040 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1a050 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1a060 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1a070 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1a080 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  on instead of in
1a090 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62  voking the .** b
1a0a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1a0b0 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1a0c0 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1a0d0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1a0e0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1a0f0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1a100 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1a110 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1a120 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1a130 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1a140 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1a150 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1a160 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1a170 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1a180 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1a190 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1a1a0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1a1b0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1a1c0 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1a1d0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1a1e0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1a1f0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1a200 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1a210 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1a220 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1a230 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1a240 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1a250 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1a260 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1a270 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1a280 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1a290 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1a2a0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1a2b0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1a2c0 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1a2d0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1a2e0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1a2f0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1a300 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1a310 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1a320 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1a330 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1a340 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1a350 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  L..**.** ^(There
1a360 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1a370 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1a380 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1a390 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1a3a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1a3b0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1a3c0 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1a3d0 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1a3e0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1a3f0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1a400 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1a410 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1a420 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  * or evaluating 
1a430 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1a440 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61  eout=N] will cha
1a450 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  nge the.** busy 
1a460 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73  handler and thus
1a470 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69   clear any previ
1a480 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68  ously set busy h
1a490 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
1a4a0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1a4b0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
1a4c0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
1a4d0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
1a4e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a4f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1a500 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1a510 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  r.  In other wor
1a520 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ds,.** the busy 
1a530 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72  handler is not r
1a540 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73  eentrant.  Any s
1a550 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
1a560 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
1a570 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
1a580 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
1a590 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
1a5a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1a5b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
1a5c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1a5d0 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
1a5e0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1a5f0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1a600 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a610 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1a620 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1a630 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1a640 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1a650 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1a660 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a670 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1a680 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1a690 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1a6a0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1a6b0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1a6c0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1a6d0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1a6e0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1a6f0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1a700 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1a710 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1a720 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1a730 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1a740 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1a750 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1a760 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1a770 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1a780 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1a790 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1a7a0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1a7b0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1a7c0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1a7d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1a7e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1a7f0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1a800 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1a810 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1a820 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1a830 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1a840 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1a850 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1a860 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1a870 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1a880 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1a890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a8a0 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1a8b0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1a8c0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1a8d0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1a8e0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1a8f0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a900 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1a910 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1a920 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1a930 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1a940 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1a950 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1a960 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1a970 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t].*/.int sqlite
1a980 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1a990 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1a9a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a9b0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1a9c0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1a9d0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1a9e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a9f0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1aa00 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1aa10 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1aa20 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1aa30 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1aa40 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1aa50 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1aa60 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1aa70 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1aa80 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1aa90 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1aaa0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1aab0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1aac0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1aad0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1aae0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1aaf0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1ab00 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1ab10 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1ab20 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1ab30 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1ab40 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1ab50 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1ab60 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1ab70 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1ab80 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1ab90 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1aba0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1abb0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1abc0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1abd0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1abe0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1abf0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1ac00 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1ac10 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1ac20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1ac30 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1ac40 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1ac50 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1ac60 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1ac70 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1ac80 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1ac90 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1aca0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1acb0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1acc0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1acd0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1ace0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1acf0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1ad00 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1ad10 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1ad20 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1ad30 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1ad40 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1ad50 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1ad60 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1ad70 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1ad80 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1ad90 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1ada0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1adb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1adc0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1add0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1ade0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1adf0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1ae00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1ae10 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1ae20 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1ae30 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1ae40 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1ae50 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1ae60 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1ae70 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1ae80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1ae90 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1aea0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1aeb0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1aec0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1aed0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1aee0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1aef0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1af00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1af10 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1af20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1af30 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1af40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1af50 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1af60 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1af70 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1af80 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1af90 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1afa0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1afb0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1afc0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1afd0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1afe0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1aff0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1b000 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1b010 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1b020 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1b030 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1b040 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1b050 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1b060 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1b070 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1b080 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b090 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1b0a0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1b0b0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1b0c0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b0d0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1b0e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b0f0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1b100 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1b110 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1b120 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1b130 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1b140 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1b150 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1b160 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1b170 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b180 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1b190 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b1a0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1b1b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b1c0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1b1d0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1b1e0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1b1f0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1b200 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1b210 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1b220 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1b230 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1b240 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1b250 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1b260 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1b270 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1b280 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1b290 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1b2a0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1b2b0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1b2c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1b2d0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1b2e0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1b2f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b300 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1b310 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1b320 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1b330 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1b340 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1b350 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1b360 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1b370 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1b380 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1b390 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1b3a0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1b3b0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1b3c0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1b3d0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1b3e0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1b3f0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1b400 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1b410 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1b420 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1b430 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1b440 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1b450 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1b460 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1b470 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1b480 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1b490 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1b4a0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1b4b0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1b4c0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1b4d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b4e0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1b4f0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1b500 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1b510 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1b520 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1b530 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1b540 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1b550 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1b560 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1b570 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1b580 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1b590 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1b5a0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1b5b0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1b5c0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1b5d0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1b5e0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1b5f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1b600 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1b610 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b620 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1b630 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1b640 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1b650 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1b660 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1b670 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1b680 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1b690 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1b6a0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1b6b0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1b6c0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1b6d0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1b6e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1b6f0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1b700 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1b710 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1b720 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1b730 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1b740 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1b750 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1b760 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1b770 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1b780 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1b790 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1b7a0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1b7b0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1b7c0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1b7d0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1b7e0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1b7f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b800 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1b810 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1b820 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1b830 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1b840 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1b850 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65  ibrary..** These
1b860 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73   routines unders
1b870 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65  tand most of the
1b880 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d   common K&R form
1b890 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a  atting options,.
1b8a0 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64  ** plus some add
1b8b0 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e  itional non-stan
1b8c0 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65  dard formats, de
1b8d0 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a  tailed below..**
1b8e0 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20   Note that some 
1b8f0 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63  of the more obsc
1b900 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  ure formatting o
1b910 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65  ptions from rece
1b920 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20  nt.** C-library 
1b930 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d  standards are om
1b940 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20  itted from this 
1b950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
1b960 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b970 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1b980 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1b990 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1b9a0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1b9b0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1b9c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1b9d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b9e0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1b9f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1ba00 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1ba10 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1ba20 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1ba30 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1ba40 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1ba50 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1ba60 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1ba70 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1ba80 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1ba90 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1baa0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1bab0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1bac0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1bad0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1bae0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1baf0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1bb00 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1bb10 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1bb20 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1bb30 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1bb40 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1bb50 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1bb60 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1bb70 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1bb80 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1bb90 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1bba0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1bbb0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1bbc0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1bbd0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1bbe0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1bbf0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1bc00 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1bc10 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1bc20 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1bc30 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1bc40 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1bc50 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1bc60 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1bc70 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1bc80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1bc90 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1bca0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1bcb0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1bcc0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1bcd0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1bce0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1bcf0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1bd00 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1bd10 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1bd20 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1bd30 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1bd40 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1bd50 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1bd60 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1bd70 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1bd80 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1bd90 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1bda0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1bdb0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1bdc0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1bdd0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1bde0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1bdf0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1be00 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1be10 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1be20 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1be30 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1be40 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1be50 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1be60 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1be70 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1be80 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1be90 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1bea0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1beb0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1bec0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1bed0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1bee0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1bef0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1bf00 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1bf10 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1bf20 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1bf30 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1bf40 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1bf50 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1bf60 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1bf70 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1bf80 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1bf90 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1bfa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1bfb0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1bfc0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1bfd0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1bfe0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1bff0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1c000 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1c010 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f   "%w" and "%z" o
1c020 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1c030 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1c040 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1c050 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1c060 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1c070 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1c080 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1c090 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1c0a0 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1c0b0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1c0c0 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1c0d0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1c0e0 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1c0f0 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1c100 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1c110 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1c120 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1c130 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1c140 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1c150 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1c160 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1c170 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1c180 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1c190 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1c1a0 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1c1b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c1c0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1c1d0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1c1e0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1c1f0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1c200 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1c210 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1c220 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1c230 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1c240 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c250 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c260 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1c270 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1c280 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c290 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1c2a0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1c2b0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1c2c0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1c2d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1c2e0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1c2f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c300 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1c310 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1c320 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1c330 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1c340 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1c350 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1c360 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1c370 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1c380 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c390 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1c3a0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1c3b0 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1c3c0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1c3d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c3e0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1c3f0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1c400 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1c410 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1c420 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1c430 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1c440 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c450 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1c460 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1c470 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1c480 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1c490 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c4a0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1c4b0 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1c4c0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1c4d0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1c4e0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1c4f0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1c500 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1c510 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1c520 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1c530 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1c540 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1c550 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1c560 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1c570 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1c580 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1c590 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1c5a0 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1c5b0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1c5c0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1c5d0 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1c5e0 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1c5f0 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1c600 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1c610 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1c620 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1c630 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1c640 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1c650 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1c660 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c670 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1c680 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1c690 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1c6a0 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1c6b0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1c6c0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1c6d0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1c6e0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1c6f0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1c700 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c710 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1c720 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1c730 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1c740 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1c750 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1c760 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1c770 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1c780 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1c790 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f  ** ^(The "%w" fo
1c7a0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1c7b0 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63  is like "%q" exc
1c7c0 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65  ept that it expe
1c7d0 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e  cts to.** be con
1c7e0 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f  tained within do
1c7f0 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74  uble-quotes inst
1c800 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75  ead of single qu
1c810 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20  otes, and it.** 
1c820 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62  escapes the doub
1c830 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
1c840 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1c850 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a  e single-quote.*
1c860 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20  * character.)^  
1c870 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1c880 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ing option is in
1c890 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c  tended for safel
1c8a0 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  y inserting.** t
1c8b0 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1c8c0 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e  names into a con
1c8d0 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61  structed SQL sta
1c8e0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tement..**.** ^(
1c8f0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1c900 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1c910 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1c920 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1c930 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1c940 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1c950 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1c960 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1c970 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1c980 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1c990 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1c9a0 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
1c9b0 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1c9c0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1c9d0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1c9e0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1c9f0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1ca00 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1ca10 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1ca20 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1ca30 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1ca40 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1ca50 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1ca60 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1ca70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ca80 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1ca90 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1caa0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1cab0 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1cac0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1cad0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1cae0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1caf0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1cb00 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1cb10 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1cb20 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1cb30 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1cb40 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1cb50 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1cb60 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1cb70 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1cb80 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1cb90 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1cba0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1cbb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cbc0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1cbd0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1cbe0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1cbf0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1cc00 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1cc10 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1cc20 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1cc30 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1cc40 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1cc50 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1cc60 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1cc70 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1cc80 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1cc90 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1cca0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1ccb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ccc0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1ccd0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1cce0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1ccf0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1cd00 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1cd10 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1cd20 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1cd30 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1cd40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1cd50 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1cd60 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1cd70 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1cd80 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1cd90 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1cda0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1cdb0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1cdc0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1cdd0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1cde0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1cdf0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1ce00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ce10 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1ce20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1ce30 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1ce40 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1ce50 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1ce60 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1ce70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1ce80 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1ce90 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1cea0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1ceb0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1cec0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1ced0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1cee0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1cef0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1cf00 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1cf10 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1cf20 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1cf30 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1cf40 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1cf50 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1cf60 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1cf70 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1cf80 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1cf90 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1cfa0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1cfb0 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1cfc0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1cfd0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1cfe0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1cff0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1d000 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1d010 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1d020 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1d030 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1d040 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d050 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1d060 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1d070 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1d080 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1d090 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1d0a0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1d0b0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1d0c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1d0d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1d0e0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1d0f0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1d100 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1d110 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1d120 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d130 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1d140 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1d150 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d160 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1d170 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1d180 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1d190 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1d1a0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1d1b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1d1c0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1d1d0 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1d1e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1d1f0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1d200 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1d210 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1d220 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1d230 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1d240 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1d250 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1d260 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1d270 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1d280 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1d290 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1d2a0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1d2b0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1d2c0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1d2d0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1d2e0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1d2f0 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1d300 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1d310 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1d320 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1d330 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1d340 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1d350 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1d360 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1d370 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1d380 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1d390 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1d3a0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1d3b0 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1d3c0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1d3d0 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1d3e0 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1d3f0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1d400 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1d410 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1d420 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1d430 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1d440 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1d450 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1d460 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1d470 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1d480 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1d490 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d4a0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1d4b0 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1d4c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1d4d0 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
1d4e0 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
1d4f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d500 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
1d510 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1d520 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
1d530 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
1d540 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
1d550 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1d560 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
1d570 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
1d580 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
1d590 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
1d5a0 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1d5b0 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
1d5c0 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
1d5d0 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
1d5e0 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
1d5f0 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
1d600 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
1d610 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
1d620 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
1d630 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
1d640 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
1d650 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
1d660 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1d670 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
1d680 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
1d690 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
1d6a0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1d6b0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1d6c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1d6d0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
1d6e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
1d6f0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1d700 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
1d710 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
1d720 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1d730 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1d740 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1d750 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1d760 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1d770 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1d780 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1d790 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1d7a0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1d7b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1d7c0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1d7d0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1d7e0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1d7f0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1d800 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1d810 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1d820 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1d830 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1d840 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1d850 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1d860 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1d870 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1d880 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1d890 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1d8a0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1d8b0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1d8c0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1d8d0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1d8e0 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1d8f0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1d900 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1d910 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1d920 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1d930 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1d940 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1d950 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1d960 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1d970 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1d980 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1d990 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1d9a0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1d9b0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1d9c0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1d9d0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1d9e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1d9f0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1da00 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1da10 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1da20 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1da30 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1da40 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1da50 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1da60 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1da70 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1da80 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1da90 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1daa0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1dab0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1dac0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1dad0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1dae0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1daf0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1db00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1db10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1db20 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1db30 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1db40 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1db50 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1db60 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1db70 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1db80 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1db90 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1dba0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1dbb0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1dbc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1dbd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1dbe0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1dbf0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1dc00 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1dc10 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
1dc20 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1dc30 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1dc40 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1dc50 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1dc60 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
1dc70 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1dc80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1dc90 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74  ee(void*);.sqlit
1dca0 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
1dcb0 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
1dcc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1dcd0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1dce0 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1dcf0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1dd00 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1dd10 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1dd20 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1dd30 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1dd40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1dd50 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1dd60 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1dd70 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1dd80 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1dd90 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1dda0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ddb0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1ddc0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1ddd0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1dde0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1ddf0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1de00 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1de10 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1de20 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1de30 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1de40 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1de50 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1de60 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1de70 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1de80 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1de90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1dea0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1deb0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1dec0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1ded0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1dee0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1def0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1df00 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1df10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1df20 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1df30 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1df40 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1df50 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1df60 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1df70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1df80 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1df90 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1dfa0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1dfb0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1dfc0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1dfd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1dfe0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1dff0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1e000 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1e010 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1e020 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1e030 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e040 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1e050 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1e060 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1e070 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1e080 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1e090 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1e0a0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1e0b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e0c0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1e0d0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1e0e0 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1e0f0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
1e100 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1e110 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
1e120 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
1e130 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1e140 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
1e150 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
1e160 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
1e170 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
1e180 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
1e190 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
1e1a0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
1e1b0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
1e1c0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
1e1d0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
1e1e0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
1e1f0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
1e200 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1e210 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
1e220 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
1e230 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
1e240 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
1e250 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1e260 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1e270 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1e280 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1e290 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1e2a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1e2b0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1e2c0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1e2d0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1e2e0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1e2f0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1e300 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1e310 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1e320 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1e330 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1e340 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
1e350 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
1e360 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
1e370 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
1e380 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
1e390 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
1e3a0 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
1e3b0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
1e3c0 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
1e3d0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
1e3e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
1e3f0 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
1e400 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
1e410 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1e420 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1e430 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
1e440 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
1e450 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1e460 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1e470 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
1e480 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
1e490 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
1e4a0 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
1e4b0 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
1e4c0 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
1e4d0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1e4e0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1e4f0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1e500 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1e510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1e520 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1e530 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1e540 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1e550 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1e560 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1e570 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1e580 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1e590 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
1e5a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1e5b0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1e5c0 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
1e5d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e5e0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
1e5f0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1e600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
1e610 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
1e620 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
1e630 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
1e640 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1e650 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
1e660 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
1e670 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
1e680 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e690 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1e6a0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
1e6b0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
1e6c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e6d0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
1e6e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e6f0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
1e700 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
1e710 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
1e720 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
1e730 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
1e740 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
1e750 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
1e760 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
1e770 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e780 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
1e790 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
1e7a0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
1e7b0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1e7c0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
1e7d0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1e7e0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
1e7f0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
1e800 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
1e810 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
1e820 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
1e830 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
1e840 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
1e850 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
1e860 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
1e870 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
1e880 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
1e890 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
1e8a0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
1e8b0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
1e8c0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
1e8d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e8e0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
1e8f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1e900 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
1e910 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
1e920 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
1e930 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1e940 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1e950 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1e960 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
1e970 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e980 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1e990 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1e9a0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1e9b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e9c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
1e9d0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
1e9e0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
1e9f0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
1ea00 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1ea10 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1ea20 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
1ea30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ea40 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1ea50 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1ea60 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
1ea70 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1ea80 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1ea90 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
1eaa0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
1eab0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
1eac0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
1ead0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1eae0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eaf0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1eb00 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
1eb10 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
1eb20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1eb30 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
1eb40 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
1eb50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
1eb60 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1eb70 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
1eb80 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
1eb90 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1eba0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
1ebb0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
1ebc0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
1ebd0 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
1ebe0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
1ebf0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
1ec00 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
1ec10 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1ec20 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
1ec30 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
1ec40 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
1ec50 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1ec60 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
1ec70 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1ec80 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
1ec90 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
1eca0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1ecb0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1ecc0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
1ecd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1ece0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
1ecf0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
1ed00 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
1ed10 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
1ed20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1ed30 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
1ed40 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
1ed50 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1ed60 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1ed70 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1ed80 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
1ed90 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
1eda0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
1edb0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
1edc0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
1edd0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
1ede0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
1edf0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1ee00 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
1ee10 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1ee20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
1ee30 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1ee40 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
1ee50 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
1ee60 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
1ee70 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
1ee80 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
1ee90 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
1eea0 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
1eeb0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
1eec0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
1eed0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
1eee0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1eef0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
1ef00 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
1ef10 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
1ef20 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
1ef30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1ef40 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
1ef50 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
1ef60 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
1ef70 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
1ef80 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
1ef90 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
1efa0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
1efb0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
1efc0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
1efd0 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
1efe0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
1eff0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
1f000 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
1f010 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
1f020 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
1f030 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
1f040 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
1f050 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
1f060 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
1f070 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
1f080 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
1f090 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
1f0a0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
1f0b0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
1f0c0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
1f0d0 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
1f0e0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
1f0f0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
1f100 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1f110 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
1f120 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
1f130 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
1f140 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
1f150 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
1f160 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
1f170 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
1f180 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
1f190 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
1f1a0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
1f1b0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
1f1c0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
1f1d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1f1e0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
1f1f0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
1f200 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
1f210 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
1f220 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
1f230 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
1f240 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
1f250 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
1f260 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
1f270 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
1f280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1f290 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
1f2a0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
1f2b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f2c0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
1f2d0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
1f2e0 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
1f2f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
1f300 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
1f310 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
1f320 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
1f330 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
1f340 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
1f350 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f360 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1f370 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1f380 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1f390 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1f3a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1f3b0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1f3c0 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1f3d0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1f3e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f3f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1f400 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1f410 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1f420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1f430 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1f440 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1f450 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1f460 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1f470 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f480 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1f490 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1f4a0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1f4b0 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1f4c0 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1f4d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1f4e0 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1f4f0 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1f500 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1f510 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1f520 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1f530 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1f540 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1f550 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1f560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1f570 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1f580 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1f590 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f5a0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1f5b0 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1f5c0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1f5d0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1f5e0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1f5f0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1f600 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1f610 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1f620 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f630 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1f640 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1f650 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1f660 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1f670 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1f680 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f690 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1f6a0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1f6b0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1f6c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f6d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1f6e0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1f6f0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1f700 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1f710 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1f720 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1f730 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1f740 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1f750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1f760 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1f770 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1f780 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f790 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1f7a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1f7b0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1f7c0 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1f7d0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1f7e0 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1f7f0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1f800 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1f810 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1f820 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1f830 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1f840 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1f850 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1f860 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1f870 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1f880 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1f890 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1f8a0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1f8b0 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1f8c0 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66   used as a [conf
1f8d0 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
1f8e0 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  mode].** returne
1f8f0 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  d from the [sqli
1f900 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1f910 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1f920 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1f930 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1f940 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1f950 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1f960 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1f970 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1f980 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1f990 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1f9a0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1f9b0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1f9c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1f9d0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1f9e0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1f9f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1fa00 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1fa10 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1fa20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1fa30 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1fa40 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1fa50 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1fa60 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1fa70 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1fa80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1fa90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1faa0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1fab0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1fac0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1fad0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1fae0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1faf0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1fb00 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1fb10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fb20 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1fb30 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1fb40 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1fb50 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1fb60 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1fb70 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1fb80 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1fb90 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1fba0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1fbb0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1fbc0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1fbd0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1fbe0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1fbf0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1fc00 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1fc10 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1fc20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1fc30 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1fc40 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1fc50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fc60 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1fc70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1fc80 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1fc90 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1fca0 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1fcb0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1fcc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1fcd0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1fce0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1fcf0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1fd00 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1fd10 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1fd20 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1fd30 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1fd40 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1fd50 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1fd60 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1fd70 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1fd80 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1fd90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fda0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1fdb0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1fdc0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1fdd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fde0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1fdf0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1fe00 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1fe10 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1fe20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1fe30 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1fe40 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1fe50 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1fe60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fe70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1fe80 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1fe90 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1fea0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1feb0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1fec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fed0 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1fee0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1fef0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ff00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ff10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ff20 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1ff30 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1ff40 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1ff50 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ff60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ff70 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1ff80 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1ff90 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1ffa0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ffb0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ffc0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1ffd0 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1ffe0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1fff0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20000 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20010 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
20020 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
20030 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20040 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20050 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
20060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
20070 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20080 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20090 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
200a0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
200b0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
200c0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
200d0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
200e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
200f0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
20100 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
20110 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20120 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20130 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20140 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
20150 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
20160 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
20170 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20180 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20190 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
201a0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
201b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
201c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
201d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
201e0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
201f0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
20200 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
20210 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20230 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
20240 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
20250 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
20260 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20280 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
20290 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
202a0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
202b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
202c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
202d0 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
202e0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
202f0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
20300 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
20320 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
20330 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
20340 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
20350 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
20370 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
20380 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
20390 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
203a0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
203b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
203c0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
203d0 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
203e0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
203f0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
20400 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
20410 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
20420 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
20430 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
20440 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20450 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
20460 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
20470 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
20480 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
20490 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
204a0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
204b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
204c0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
204d0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
204e0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
204f0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
20500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
20510 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
20520 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20540 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
20550 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
20560 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
20570 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
20580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20590 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
205a0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
205b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
205c0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
205d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
205e0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
205f0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
20600 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20610 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20630 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
20640 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
20650 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20660 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20680 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
20690 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
206a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
206b0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
206c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
206d0 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
206e0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
206f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20700 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
20710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20720 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
20730 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
20740 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
20750 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
20760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20770 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
20780 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
20790 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
207a0 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
207b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
207c0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
207d0 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
207e0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
207f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
20800 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
20810 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
20820 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
20830 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
20840 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
20850 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
20860 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
20870 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
20880 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  3.**.** These ro
20890 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
208a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
208b0 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
208c0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
208d0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
208e0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
208f0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
20900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
20910 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
20920 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
20930 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
20940 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
20950 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
20960 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20970 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
20980 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
20990 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
209a0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
209b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
209c0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
209d0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
209e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
209f0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
20a00 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
20a10 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
20a20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
20a30 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
20a40 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
20a50 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
20a60 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
20a70 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
20a80 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
20a90 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
20aa0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
20ab0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
20ac0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
20ad0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
20ae0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
20af0 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
20b00 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
20b10 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
20b20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
20b30 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
20b40 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
20b50 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
20b60 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
20b70 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
20b80 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20b90 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
20ba0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
20bb0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
20bc0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
20bd0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
20be0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
20bf0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
20c00 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
20c10 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
20c20 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
20c30 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
20c40 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
20c50 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
20c60 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
20c70 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20c80 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
20c90 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
20ca0 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
20cb0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
20cc0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
20cd0 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
20ce0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
20cf0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
20d00 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
20d10 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
20d20 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
20d30 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
20d40 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
20d50 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
20d60 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
20d70 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
20d80 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
20d90 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
20da0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
20db0 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
20dc0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
20dd0 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
20de0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
20df0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
20e00 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
20e10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
20e20 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
20e30 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
20e40 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
20e50 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
20e60 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
20e70 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
20e80 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
20e90 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
20ea0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
20eb0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
20ec0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
20ed0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
20ee0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
20ef0 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
20f00 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
20f10 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
20f20 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
20f30 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
20f40 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
20f50 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
20f60 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
20f70 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
20f80 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
20f90 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
20fa0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
20fb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
20fc0 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
20fd0 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
20fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20ff0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
21000 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
21010 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
21020 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
21030 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
21040 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
21050 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
21060 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
21070 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
21080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21090 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
210a0 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
210b0 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
210c0 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
210d0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
210e0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
210f0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
21100 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
21110 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
21120 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
21130 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
21140 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
21150 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
21160 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
21170 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
21180 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
21190 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
211a0 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
211b0 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
211c0 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
211d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
211e0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
211f0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
21200 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
21210 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
21220 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
21230 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
21240 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
21250 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
21260 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
21270 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
21280 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
21290 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
212a0 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
212b0 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
212c0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
212d0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
212e0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
212f0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
21300 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
21310 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
21320 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
21330 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
21340 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
21350 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
21360 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21370 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
21380 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
21390 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
213a0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
213b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
213c0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
213d0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
213e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
213f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21400 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21410 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
21420 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
21430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21440 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
21450 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
21460 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
21470 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
21480 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
21490 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
214a0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
214b0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
214c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
214d0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
214e0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
214f0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
21500 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
21510 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
21520 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
21530 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
21540 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
21550 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
21560 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
21570 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
21580 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
21590 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
215a0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
215b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
215c0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
215d0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
215e0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
215f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
21600 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
21610 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
21620 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
21630 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
21640 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
21650 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
21660 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
21670 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
21680 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
21690 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
216a0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
216b0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
216c0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
216d0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
216e0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
216f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
21700 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
21710 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
21720 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21730 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
21740 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
21750 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
21760 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
21770 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
21780 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
21790 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
217a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
217b0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
217c0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
217d0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
217e0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
217f0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
21800 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
21810 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
21820 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
21830 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
21840 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
21850 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
21860 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
21870 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
21880 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
21890 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
218a0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
218b0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
218c0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
218d0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
218e0 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
218f0 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
21900 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
21910 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
21920 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
21930 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
21940 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
21950 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
21960 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
21970 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
21980 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
21990 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
219a0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
219b0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
219c0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
219d0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
219e0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
219f0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
21a00 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
21a10 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
21a20 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
21a30 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
21a40 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
21a50 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
21a60 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
21a70 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
21a80 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
21a90 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
21aa0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
21ab0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
21ac0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
21ad0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
21ae0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
21af0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
21b00 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
21b10 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
21b20 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
21b30 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
21b40 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
21b50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
21b60 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
21b70 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
21b80 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
21b90 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
21ba0 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
21bb0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
21bc0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
21bd0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21be0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
21bf0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
21c00 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21c10 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
21c20 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
21c30 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
21c40 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
21c50 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
21c60 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
21c70 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
21c80 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21c90 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
21ca0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21cb0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
21cc0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
21cd0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
21ce0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
21cf0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
21d00 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
21d10 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
21d20 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
21d30 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
21d40 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
21d50 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
21d60 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
21d70 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
21d80 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
21d90 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21da0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
21db0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
21dc0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
21dd0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
21de0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
21df0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
21e00 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
21e10 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
21e20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
21e30 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
21e40 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
21e50 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
21e60 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
21e70 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
21e80 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
21e90 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
21ea0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21eb0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
21ec0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
21ed0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
21ee0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
21ef0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
21f00 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
21f10 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21f20 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
21f30 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
21f40 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
21f50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
21f60 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
21f70 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
21f80 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
21f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21fa0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
21fb0 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
21fc0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
21fd0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
21fe0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
21ff0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
22000 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
22010 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
22020 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
22030 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
22040 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
22050 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
22060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22070 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
22080 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
22090 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
220a0 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
220b0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
220c0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
220d0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
220e0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
220f0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
22100 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
22110 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
22120 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
22130 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
22140 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
22150 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
22160 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
22170 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
22180 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
22190 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
221a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
221b0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
221c0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
221d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
221e0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
221f0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
22200 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
22210 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
22220 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
22230 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
22240 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
22250 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
22260 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
22270 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22280 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
22290 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
222a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
222b0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
222c0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
222d0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
222e0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
222f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
22300 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
22310 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
22320 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
22330 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
22340 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
22350 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
22360 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
22370 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
22380 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
22390 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
223a0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
223b0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
223c0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
223d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
223e0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
223f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
22400 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
22410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22420 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
22430 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
22440 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
22450 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
22460 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
22470 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
22480 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
22490 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
224a0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
224b0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
224c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
224d0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
224e0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
224f0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
22500 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
22510 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
22520 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
22530 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
22540 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
22550 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
22560 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
22570 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
22580 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
22590 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
225a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
225b0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
225c0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
225d0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
225e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
225f0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
22600 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
22610 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
22620 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
22630 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
22640 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
22650 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
22660 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
22670 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
22680 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
22690 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
226a0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
226b0 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
226c0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
226d0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
226e0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
226f0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
22700 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
22710 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
22720 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
22730 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
22740 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
22750 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
22760 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22770 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
22780 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
22790 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
227a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
227b0 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
227c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
227d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
227e0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
227f0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
22800 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
22810 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
22820 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
22830 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
22840 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
22850 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
22860 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
22870 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
22880 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22890 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
228a0 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
228b0 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
228c0 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
228d0 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
228e0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
228f0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
22900 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
22910 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
22920 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
22930 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
22940 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
22950 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
22960 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
22970 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
22980 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
22990 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
229a0 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
229b0 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
229c0 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
229d0 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
229e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
229f0 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
22a00 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
22a10 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
22a20 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
22a30 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
22a40 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
22a50 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
22a60 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
22a70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
22a80 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
22a90 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
22aa0 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
22ab0 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
22ac0 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
22ad0 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
22ae0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
22af0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
22b00 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
22b10 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
22b20 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
22b30 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
22b40 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
22b50 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
22b60 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
22b70 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
22b80 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
22b90 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
22ba0 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
22bb0 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
22bc0 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
22bd0 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
22be0 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
22bf0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
22c00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
22c10 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
22c20 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
22c30 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
22c40 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
22c50 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
22c60 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
22c70 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
22c80 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
22c90 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
22ca0 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
22cb0 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
22cc0 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
22cd0 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
22ce0 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
22cf0 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
22d00 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
22d10 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
22d20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
22d30 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
22d40 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
22d50 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
22d60 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
22d70 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
22d80 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
22d90 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
22da0 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
22db0 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
22dc0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
22dd0 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
22de0 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
22df0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
22e00 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
22e10 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
22e20 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
22e30 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
22e40 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
22e50 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
22e60 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
22e70 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
22e80 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
22e90 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
22ea0 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
22eb0 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
22ec0 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
22ed0 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
22ee0 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
22ef0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
22f00 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
22f10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22f20 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
22f30 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
22f40 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
22f50 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22f60 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
22f70 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
22f80 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
22f90 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
22fa0 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
22fb0 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
22fc0 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
22fd0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
22fe0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
22ff0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
23000 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
23010 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
23020 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
23030 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
23040 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
23050 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
23060 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
23070 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
23080 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
23090 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
230a0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
230b0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
230c0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
230d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
230e0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
230f0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
23100 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
23110 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
23120 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
23130 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
23140 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
23150 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
23160 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
23170 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
23180 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
23190 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
231a0 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
231b0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
231c0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
231d0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
231e0 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
231f0 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
23200 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
23210 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
23220 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
23230 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
23240 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
23250 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
23260 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
23270 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
23280 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
23290 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
232a0 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
232b0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
232c0 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
232d0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
232e0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
232f0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
23300 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
23310 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
23320 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
23330 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
23340 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
23350 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
23360 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
23370 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
23380 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
23390 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
233a0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
233b0 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
233c0 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
233d0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
233e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
233f0 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
23400 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
23410 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
23420 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
23430 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
23440 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
23450 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
23460 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
23470 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
23480 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
23490 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
234a0 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
234b0 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
234c0 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
234d0 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
234e0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
234f0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
23500 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
23510 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
23520 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
23530 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
23540 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
23550 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
23560 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
23570 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
23580 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
23590 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
235a0 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
235b0 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
235c0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
235d0 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
235e0 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
235f0 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
23600 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
23610 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
23620 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
23630 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
23640 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
23650 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
23660 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
23670 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
23680 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
23690 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
236a0 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
236b0 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
236c0 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
236d0 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
236e0 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
236f0 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
23700 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
23710 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
23720 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
23730 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
23740 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
23750 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
23760 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
23770 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
23780 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
23790 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
237a0 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
237b0 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
237c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
237d0 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
237e0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
237f0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
23800 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
23810 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
23820 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
23830 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
23840 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
23850 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
23860 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
23870 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
23880 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
23890 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
238a0 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
238b0 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
238c0 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
238d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
238e0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
238f0 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
23900 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
23910 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
23920 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
23930 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
23940 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
23950 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
23960 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
23970 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
23980 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
23990 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
239a0 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
239b0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
239c0 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
239d0 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
239e0 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
239f0 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
23a00 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
23a10 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
23a20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
23a30 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
23a40 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
23a50 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
23a60 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
23a70 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23a80 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
23a90 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
23aa0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
23ab0 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
23ac0 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
23ad0 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
23ae0 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
23af0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
23b00 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
23b10 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
23b20 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
23b30 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
23b40 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
23b50 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
23b60 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
23b70 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
23b80 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
23b90 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
23ba0 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
23bb0 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
23bc0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
23bd0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
23be0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
23bf0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
23c00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23c10 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
23c20 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
23c30 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
23c40 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
23c50 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
23c60 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
23c70 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
23c80 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
23c90 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
23ca0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23cb0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
23cc0 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
23cd0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
23ce0 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
23cf0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
23d00 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
23d10 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
23d20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
23d30 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
23d40 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
23d50 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
23d60 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
23d70 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
23d80 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
23d90 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
23da0 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
23db0 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
23dc0 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
23dd0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
23de0 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
23df0 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
23e00 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
23e10 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
23e20 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
23e30 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
23e40 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
23e50 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
23e60 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
23e70 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
23e80 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
23e90 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
23ea0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23eb0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
23ec0 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
23ed0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23ee0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
23ef0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
23f00 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
23f10 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
23f20 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
23f30 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
23f40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
23f50 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
23f60 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
23f70 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
23f80 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
23f90 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
23fa0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
23fb0 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
23fc0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
23fd0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
23fe0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
23ff0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
24000 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
24010 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
24020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
24030 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
24040 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
24050 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
24060 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
24070 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
24080 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
24090 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
240a0 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
240b0 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
240c0 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
240d0 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
240e0 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
240f0 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
24100 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
24110 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
24120 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
24130 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
24140 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
24150 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
24160 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
24170 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
24180 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
24190 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
241a0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
241b0 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
241c0 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
241d0 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
241e0 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
241f0 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
24200 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
24210 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
24220 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
24230 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
24240 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
24250 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
24260 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
24270 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
24280 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
24290 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
242a0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
242b0 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
242c0 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
242d0 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
242e0 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
242f0 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
24300 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
24310 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
24320 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
24330 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
24340 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
24350 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
24360 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
24370 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
24380 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
24390 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
243a0 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
243b0 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
243c0 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
243d0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
243e0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
243f0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
24400 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
24410 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
24420 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
24430 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
24440 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
24450 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
24460 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
24470 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
24480 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
24490 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
244a0 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
244b0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
244c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
244d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
244e0 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
244f0 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
24500 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
24510 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
24520 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
24530 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
24540 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
24550 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
24560 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
24570 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
24580 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
24590 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
245a0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
245b0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
245c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
245d0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
245e0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
245f0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
24600 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
24610 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
24620 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
24630 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
24640 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
24650 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
24660 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
24670 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
24680 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
24690 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
246a0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
246b0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
246c0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
246d0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
246e0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
246f0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
24700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
24710 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
24720 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
24730 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
24740 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
24750 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
24760 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
24770 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
24780 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
24790 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
247a0 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
247b0 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
247c0 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
247d0 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
247e0 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
247f0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
24800 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
24810 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
24820 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
24830 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
24840 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
24850 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
24860 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
24870 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
24880 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
24890 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
248a0 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
248b0 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
248c0 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
248d0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
248e0 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
248f0 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
24900 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
24910 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
24920 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
24930 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
24940 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
24950 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
24960 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
24970 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
24980 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
24990 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
249a0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
249b0 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
249c0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
249d0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
249e0 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
249f0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
24a00 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
24a10 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24a20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
24a30 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
24a40 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
24a50 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
24a60 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
24a70 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
24a80 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
24a90 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
24aa0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
24ab0 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
24ac0 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
24ad0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
24ae0 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
24af0 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
24b00 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
24b10 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
24b20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
24b30 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
24b40 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
24b50 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
24b60 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
24b70 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
24b80 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
24b90 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
24ba0 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
24bb0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
24bc0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
24bd0 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
24be0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
24bf0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24c00 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
24c10 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
24c20 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
24c30 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
24c40 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
24c50 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
24c60 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
24c70 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
24c80 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
24c90 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
24ca0 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
24cb0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
24cc0 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
24cd0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
24ce0 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
24cf0 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
24d00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24d10 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24d20 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
24d30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24d40 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
24d50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
24d60 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
24d70 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
24d80 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
24d90 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
24da0 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
24db0 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
24dc0 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
24dd0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
24de0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
24df0 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
24e00 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
24e10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
24e20 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
24e30 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
24e40 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
24e50 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
24e60 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
24e70 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24e80 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
24e90 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
24ea0 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
24eb0 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
24ec0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
24ed0 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
24ee0 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
24ef0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
24f00 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
24f10 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
24f20 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
24f30 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
24f40 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
24f50 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
24f60 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24f70 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24f80 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
24f90 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
24fa0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
24fb0 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
24fc0 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
24fd0 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
24fe0 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
24ff0 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
25000 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
25010 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
25020 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
25030 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
25040 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
25050 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
25060 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
25070 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
25080 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
25090 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
250a0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
250b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
250c0 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
250d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
250e0 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
250f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
25100 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
25110 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
25120 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
25130 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
25140 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
25150 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
25160 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
25170 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
25180 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
25190 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
251a0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
251b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
251c0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
251d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
251e0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
251f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
25200 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
25210 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
25220 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
25230 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
25240 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
25250 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
25260 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
25270 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
25280 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
25290 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
252a0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
252b0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
252c0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
252d0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
252e0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
252f0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
25300 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
25310 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
25320 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
25330 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
25340 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
25350 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
25360 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
25370 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
25380 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
25390 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
253a0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
253b0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
253c0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
253d0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
253e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
253f0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
25400 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
25410 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
25420 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
25430 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25440 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
25450 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
25460 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
25470 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
25480 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
25490 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
254a0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
254b0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
254c0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
254d0 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
254e0 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
254f0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
25500 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
25510 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
25520 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
25530 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
25540 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
25550 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
25560 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
25570 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
25580 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
25590 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
255a0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
255b0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
255c0 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
255d0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
255e0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
255f0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
25600 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
25610 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
25620 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
25630 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
25640 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
25650 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
25660 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
25670 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
25680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25690 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
256a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
256b0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
256c0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
256d0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
256e0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
256f0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
25700 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
25710 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
25720 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
25730 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
25740 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
25750 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
25760 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
25770 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
25780 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
25790 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
257a0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
257b0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
257c0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
257d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
257e0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
257f0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
25800 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
25810 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
25820 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
25830 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
25840 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
25850 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
25860 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
25870 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
25880 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
25890 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
258a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
258b0 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
258c0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
258d0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
258e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
258f0 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
25900 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
25910 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
25920 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
25930 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
25940 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
25950 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
25960 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
25970 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
25980 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a  tatement that.**
25990 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c   has been compil
259a0 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66  ed into binary f
259b0 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79  orm and is ready
259c0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
259d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66  ..**.** Think of
259e0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
259f0 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74  ent as a separat
25a00 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72  e computer progr
25a10 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67  am.  The.** orig
25a20 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73  inal SQL text is
25a30 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41   source code.  A
25a40 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25a50 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69  ent object .** i
25a60 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f  s the compiled o
25a70 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c  bject code.  All
25a80 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e   SQL must be con
25a90 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a  verted into a.**
25aa0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25ab0 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61  ent before it ca
25ac0 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  n be run..**.** 
25ad0 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f  The life-cycle o
25ae0 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
25af0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
25b00 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20  ually goes like 
25b10 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
25b20 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
25b30 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
25b40 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
25b50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
25b60 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c  pare_v2()]..** <
25b70 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
25b80 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  to [parameters] 
25b90 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
25ba0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
25bb0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
25bc0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
25bd0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
25be0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
25bf0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
25c00 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
25c10 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
25c20 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
25c30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
25c40 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
25c50 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
25c60 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
25c70 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
25c80 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
25c90 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
25ca0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25cb0 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74  ]..** </ol>.*/.t
25cc0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
25cd0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
25ce0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
25cf0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
25d00 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54  me Limits.** MET
25d10 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
25d20 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
25d30 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
25d40 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
25d50 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
25d60 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
25d70 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
25d80 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
25d90 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
25da0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
25db0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25dc0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
25dd0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
25de0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
25df0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
25e00 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
25e10 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
25e20 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
25e30 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
25e40 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
25e50 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
25e60 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25e70 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
25e80 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
25e90 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
25ea0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
25eb0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
25ec0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
25ed0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
25ee0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
25ef0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
25f00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
25f10 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
25f20 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
25f30 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25f40 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
25f50 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
25f60 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
25f70 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
25f80 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
25f90 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
25fa0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
25fb0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
25fc0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
25fd0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
25fe0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
25ff0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
26000 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
26010 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
26020 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
26030 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
26040 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
26050 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
26060 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
26070 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
26080 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
26090 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
260a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
260b0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
260c0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
260d0 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
260e0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
260f0 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
26100 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
26110 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
26120 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
26130 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
26140 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
26150 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
26160 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
26170 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
26180 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
26190 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
261a0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
261b0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
261c0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
261d0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
261e0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
261f0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
26200 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
26210 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
26220 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
26230 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
26240 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
26250 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
26260 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
26270 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
26280 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
26290 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
262a0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
262b0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
262c0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
262d0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
262e0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
262f0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
26300 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
26310 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
26320 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
26330 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
26340 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
26350 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
26360 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
26370 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
26380 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
26390 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
263a0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
263b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
263c0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
263d0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
263e0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
263f0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
26400 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
26410 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
26420 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
26430 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
26440 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
26450 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
26460 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
26470 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
26480 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
26490 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
264a0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
264b0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
264c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
264d0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
264e0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
264f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
26500 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
26510 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
26520 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
26530 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
26540 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
26550 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
26560 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
26570 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
26580 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
26590 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
265a0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
265b0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
265c0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
265d0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
265e0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
265f0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
26600 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
26610 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
26620 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
26630 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
26640 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
26650 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
26660 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
26670 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26680 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
26690 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
266a0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
266b0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
266c0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
266d0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
266e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
266f0 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
26700 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
26710 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
26720 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26730 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
26740 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
26750 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
26760 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26770 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
26780 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26790 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
267a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
267b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
267c0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
267d0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
267e0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
267f0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
26800 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
26810 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26820 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
26830 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
26840 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
26850 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
26860 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
26870 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
26880 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
26890 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
268a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
268b0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
268c0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
268d0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
268e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
268f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
26900 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
26910 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
26920 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
26930 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26940 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26950 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
26960 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
26970 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
26980 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26990 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
269a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
269b0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
269c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
269d0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
269e0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
269f0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
26a00 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
26a10 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
26a20 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
26a30 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
26a40 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
26a50 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
26a60 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
26a70 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
26a80 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
26a90 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
26aa0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26ab0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
26ac0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26ad0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
26ae0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26af0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26b00 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
26b10 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
26b20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26b30 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
26b40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26b50 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
26b60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26b70 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
26b80 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
26b90 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
26ba0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
26bb0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
26bc0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
26bd0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
26be0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
26bf0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
26c00 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26c10 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
26c20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
26c30 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
26c40 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
26c50 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
26c60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26c70 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
26c80 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
26c90 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
26ca0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
26cb0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26cc0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
26cd0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
26ce0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
26cf0 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
26d00 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
26d10 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
26d20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26d30 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
26d40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26d50 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
26d60 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
26d70 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
26d80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26d90 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26da0 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
26db0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
26dc0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
26dd0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26de0 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
26df0 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
26e00 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
26e10 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
26e20 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
26e30 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
26e40 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
26e50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
26e60 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
26e70 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
26e80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
26e90 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
26ea0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
26eb0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
26ec0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
26ed0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
26ee0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
26ef0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
26f00 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
26f10 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26f20 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
26f30 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
26f40 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26f50 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
26f60 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
26f70 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26f80 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
26f90 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
26fa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26fb0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
26fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
26fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26fe0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
26ff0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
27000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27010 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
27020 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
27030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27040 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
27050 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
27060 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
27070 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
27080 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
27090 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
270a0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
270b0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
270c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
270d0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
270e0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
270f0 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54  sqlite3.** CONST
27100 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
27110 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  stmt.**.** To ex
27120 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
27130 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
27140 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
27150 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
27160 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
27170 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
27180 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
27190 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
271a0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
271b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
271c0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
271d0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
271e0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
271f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
27200 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
27210 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
27220 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
27230 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
27240 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
27250 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
27260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
27270 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
27280 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
27290 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
272a0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
272b0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
272c0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
272d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
272e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
272f0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
27300 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
27310 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
27320 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
27330 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27340 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
27350 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
27360 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
27370 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ent is negative,
27380 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
27390 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
273a0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
273b0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
273c0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
273d0 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20  en it is the.** 
273e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
273f0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
27400 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65   ^If nByte is ze
27410 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70  ro, then no prep
27420 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
27430 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a  t is generated..
27440 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  ** If the caller
27450 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20   knows that the 
27460 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
27470 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
27480 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65  d, then.** there
27490 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66   is a small perf
274a0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
274b0 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20  e to passing an 
274c0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
274d0 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e  that.** is the n
274e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
274f0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
27500 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
27510 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
27520 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
27530 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
27540 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
27550 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
27560 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
27570 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
27580 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
27590 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
275a0 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
275b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
275c0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
275d0 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
275e0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
275f0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
27600 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
27610 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
27620 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
27630 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
27640 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
27650 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
27660 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
27670 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
27680 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
27690 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
276a0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
276b0 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
276c0 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
276d0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
276e0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
276f0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
27700 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
27710 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
27720 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
27730 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
27740 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
27750 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
27760 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
27770 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
27780 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
27790 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
277a0 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
277b0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
277c0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
277d0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
277e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
277f0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
27800 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
27810 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
27820 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
27830 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
27840 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
27850 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
27860 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27870 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
27880 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
27890 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
278a0 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
278b0 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
278c0 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
278d0 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
278e0 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
278f0 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
27900 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
27910 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
27920 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
27930 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
27940 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
27950 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27960 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
27970 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
27980 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
27990 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
279a0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
279b0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
279c0 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
279d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
279e0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
279f0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
27a00 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
27a10 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
27a20 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
27a30 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
27a40 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
27a50 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
27a60 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
27a70 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
27a80 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
27a90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
27aa0 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
27ab0 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
27ac0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
27ad0 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
27ae0 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
27af0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
27b00 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
27b10 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
27b20 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
27b30 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
27b40 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
27b50 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
27b60 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
27b70 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
27b80 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
27b90 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
27ba0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
27bb0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
27bc0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
27bd0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
27be0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
27bf0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
27c00 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
27c10 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
27c20 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
27c30 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
27c40 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
27c50 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
27c60 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
27c70 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
27c80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
27c90 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
27ca0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
27cb0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
27cc0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
27cd0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
27ce0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
27cf0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
27d00 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
27d10 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
27d20 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
27d30 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
27d40 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
27d50 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
27d60 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
27d70 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
27d80 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
27d90 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
27da0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
27db0 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
27dc0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
27dd0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
27de0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
27df0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
27e00 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
27e10 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
27e20 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
27e30 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
27e40 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
27e50 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
27e60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
27e70 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
27e80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
27e90 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
27ea0 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
27eb0 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
27ec0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
27ed0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
27ee0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
27ef0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
27f00 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
27f10 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
27f20 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
27f30 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
27f40 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
27f50 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
27f60 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
27f70 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
27f80 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
27f90 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
27fa0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
27fb0 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
27fc0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
27fd0 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
27fe0 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ol>.*/.int sql
27ff0 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
28000 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
28010 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
28020 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
28030 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
28040 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28050 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
28060 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
28070 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
28080 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
28090 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
280a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
280b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
280c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
280d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
280e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
280f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
28100 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
28110 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
28120 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
28130 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28140 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
28150 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28160 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28170 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28180 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
28190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
281a0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
281b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
281c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
281d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
281e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
281f0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28200 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28210 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28220 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28230 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
28240 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28250 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28260 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28270 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
28280 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
28290 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
282a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
282b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
282c0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
282d0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
282e0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
282f0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
28300 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
28310 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
28320 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
28330 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
28340 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
28350 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
28360 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
28370 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
28380 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
28390 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
283a0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
283b0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
283c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
283d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
283e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
283f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
28400 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
28410 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
28420 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
28430 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
28440 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
28450 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
28460 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
28470 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
28480 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
28490 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
284a0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
284b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
284c0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
284d0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
284e0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
284f0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
28500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28510 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
28520 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
28530 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
28540 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  mt.**.** ^This i
28550 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
28560 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
28570 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
28580 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
28590 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
285a0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
285b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
285c0 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
285d0 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
285e0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
285f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28600 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
28610 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
28620 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
28630 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
28640 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
28650 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28660 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
28670 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
28680 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
28690 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
286a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
286b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
286c0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
286d0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
286e0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
286f0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
28700 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
28710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28720 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
28730 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
28740 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
28750 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28760 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
28770 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
28780 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28790 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
287a0 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
287b0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
287c0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
287d0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
287e0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
287f0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
28800 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
28810 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
28820 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
28830 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
28840 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
28850 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
28860 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
28870 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
28880 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
28890 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
288a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
288b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
288c0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
288d0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
288e0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
288f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
28900 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
28910 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
28920 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
28930 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
28940 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
28950 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
28960 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
28970 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
28980 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
28990 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
289a0 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
289b0 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
289c0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
289d0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
289e0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
289f0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
28a00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
28a10 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
28a20 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
28a30 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
28a40 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
28a50 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
28a60 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
28a70 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
28a80 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
28a90 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
28aa0 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
28ab0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
28ac0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
28ad0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
28ae0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
28af0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
28b00 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
28b10 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
28b20 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
28b30 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
28b40 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
28b50 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
28b60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
28b70 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
28b80 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
28b90 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
28ba0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
28bb0 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74   on disk..*/.int
28bc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28bd0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
28be0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
28bf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
28c00 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
28c10 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
28c20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
28c30 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28c40 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
28c50 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
28c60 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
28c70 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
28c80 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
28c90 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
28ca0 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
28cb0 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
28cc0 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
28cd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
28ce0 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
28cf0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
28d00 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
28d10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
28d20 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
28d30 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
28d40 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
28d50 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
28d60 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
28d70 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
28d80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
28d90 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
28da0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
28db0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
28dc0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
28dd0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
28de0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
28df0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
28e00 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
28e10 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
28e20 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
28e30 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
28e40 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
28e50 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
28e60 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
28e70 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
28e80 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
28e90 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
28ea0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
28eb0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
28ec0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
28ed0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
28ee0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
28ef0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
28f00 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
28f10 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
28f20 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
28f30 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
28f40 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
28f50 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
28f60 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
28f70 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
28f80 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
28f90 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
28fa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
28fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28fc0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
28fd0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
28fe0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
28ff0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29000 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
29010 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29020 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
29030 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
29040 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
29050 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
29060 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
29070 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
29080 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
29090 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
290a0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
290b0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
290c0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
290d0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
290e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
290f0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
29100 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
29110 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
29120 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
29130 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
29140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29150 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
29160 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
29170 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
29180 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
29190 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
291a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
291b0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
291c0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
291d0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
291e0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
291f0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
29200 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
29210 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
29220 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
29230 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
29240 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
29250 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
29260 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
29270 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29280 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
29290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
292a0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
292b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
292c0 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
292d0 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
292e0 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
292f0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
29300 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
29310 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
29320 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
29330 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
29340 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
29350 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
29360 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
29370 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
29380 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
29390 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
293a0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
293b0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
293c0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
293d0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
293e0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
293f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
29400 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
29410 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
29420 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
29430 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
29440 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
29450 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
29460 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
29470 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
29480 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
29490 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
294a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
294b0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
294c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
294d0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
294e0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
294f0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
29500 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
29510 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
29520 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29530 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
29540 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
29550 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
29560 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
29570 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
29580 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
29590 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
295a0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
295b0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
295c0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
295d0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
295e0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
295f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29600 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
29610 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
29620 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29630 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29640 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
29650 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
29660 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
29670 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
29680 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29690 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
296a0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
296b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
296c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
296d0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
296e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
296f0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
29700 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
29710 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29720 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
29730 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
29740 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
29750 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
29760 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
29770 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
29780 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29790 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
297a0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
297b0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
297c0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
297d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
297e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
297f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
29800 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
29810 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
29820 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
29830 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
29840 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
29850 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
29860 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
29870 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
29880 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
29890 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
298a0 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
298b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
298c0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
298d0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
298e0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
298f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29900 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
29910 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
29920 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
29930 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
29940 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
29950 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
29960 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
29970 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
29980 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
29990 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
299a0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
299b0 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
299c0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
299d0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
299e0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
299f0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
29a00 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
29a10 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
29a20 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
29a30 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
29a40 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
29a50 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
29a60 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
29a70 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
29a80 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
29a90 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
29aa0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
29ab0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
29ac0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
29ad0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
29ae0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
29af0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
29b00 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
29b10 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
29b20 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ding}.** METHOD:
29b30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
29b40 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
29b50 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
29b60 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
29b70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29b80 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
29b90 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
29ba0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
29bb0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
29bc0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
29bd0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
29be0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
29bf0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
29c00 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
29c10 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
29c20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
29c30 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
29c40 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
29c50 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
29c60 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
29c70 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
29c80 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
29c90 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
29ca0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
29cb0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
29cc0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
29cd0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
29ce0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
29cf0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
29d00 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
29d10 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
29d20 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
29d30 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
29d40 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
29d50 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
29d60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
29d70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29d80 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
29d90 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
29da0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
29db0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
29dc0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
29dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
29de0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
29df0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
29e00 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
29e10 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
29e20 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
29e30 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
29e40 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
29e50 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
29e60 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
29e70 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
29e80 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
29e90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
29ea0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
29eb0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
29ec0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
29ed0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
29ee0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
29ef0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
29f00 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
29f10 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
29f20 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
29f30 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
29f40 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
29f50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29f60 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
29f70 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
29f80 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
29f90 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
29fa0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
29fb0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
29fc0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
29fd0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
29fe0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
29ff0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
2a000 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2a010 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
2a020 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
2a030 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
2a040 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2a050 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
2a060 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
2a070 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2a080 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2a090 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2a0a0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2a0b0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2a0c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2a0d0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
2a0e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
2a0f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a100 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
2a110 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
2a120 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
2a130 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
2a140 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
2a150 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2a160 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2a170 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2a180 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2a190 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2a1a0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2a1b0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2a1c0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2a1d0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2a1e0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2a1f0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2a200 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2a210 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2a220 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2a230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2a240 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2a250 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2a260 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2a270 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2a280 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2a290 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2a2a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2a2b0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2a2c0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2a2d0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2a2e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2a2f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2a300 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2a310 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2a320 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2a330 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2a340 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2a350 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2a360 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2a370 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2a380 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2a390 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
2a3a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2a3b0 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
2a3c0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2a3d0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2a3e0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2a3f0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2a400 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2a410 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2a420 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2a430 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2a440 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2a450 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2a460 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2a470 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2a480 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a490 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2a4a0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2a4b0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2a4c0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2a4d0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2a4e0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2a4f0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2a500 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2a510 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2a520 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2a530 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2a540 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
2a550 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
2a560 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
2a570 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2a580 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2a590 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2a5a0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2a5b0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2a5c0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2a5d0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2a5e0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2a5f0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2a600 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2a610 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
2a620 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
2a630 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2a640 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2a650 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2a660 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2a670 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2a680 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2a690 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2a6a0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2a6b0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2a6c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2a6d0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2a6e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2a6f0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2a700 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2a710 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2a720 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2a730 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2a740 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2a750 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2a760 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a770 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2a780 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2a790 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2a7a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a7b0 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
2a7c0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
2a7d0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2a7e0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
2a7f0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2a800 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
2a810 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
2a820 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2a830 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
2a840 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
2a850 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
2a860 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2a870 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2a880 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
2a890 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
2a8a0 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
2a8b0 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
2a8c0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2a8d0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
2a8e0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2a8f0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
2a900 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
2a910 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
2a920 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2a930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a940 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2a950 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2a960 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2a970 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2a980 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2a990 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2a9a0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2a9b0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2a9c0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2a9d0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2a9e0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2a9f0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2aa00 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2aa10 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2aa20 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2aa30 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2aa40 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2aa50 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2aa60 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2aa70 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2aa80 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2aa90 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2aaa0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2aab0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2aac0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2aad0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2aae0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
2aaf0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2ab00 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2ab10 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
2ab20 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2ab30 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
2ab40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ab50 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
2ab60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
2ab70 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
2ab80 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2ab90 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
2aba0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
2abb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2abc0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
2abd0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
2abe0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2abf0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
2ac00 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
2ac10 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
2ac20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ac30 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
2ac40 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
2ac50 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
2ac60 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2ac70 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
2ac80 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
2ac90 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
2aca0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
2acb0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
2acc0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
2acd0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
2ace0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
2acf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ad00 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
2ad10 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2ad20 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2ad30 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
2ad40 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
2ad50 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
2ad60 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
2ad70 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
2ad80 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
2ad90 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
2ada0 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
2adb0 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
2adc0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2add0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2ade0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
2adf0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
2ae00 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
2ae10 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
2ae20 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
2ae30 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
2ae40 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
2ae50 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
2ae60 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
2ae70 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
2ae80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2ae90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2aea0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
2aeb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2aec0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2aed0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2aee0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2aef0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
2af00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2af10 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2af20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2af30 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2af40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2af50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2af60 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2af70 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2af80 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
2af90 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2afa0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2afb0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2afc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
2afd0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2afe0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2aff0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b000 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
2b010 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
2b020 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2b030 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
2b040 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2b050 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
2b060 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2b070 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
2b080 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2b090 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2b0a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
2b0b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
2b0c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b0d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2b0e0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
2b0f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b100 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2b110 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b120 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b130 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
2b140 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2b150 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2b160 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2b170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b180 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2b190 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
2b1a0 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73  encoding);.int s
2b1b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2b1c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b1d0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2b1e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2b1f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2b200 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2b210 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2b220 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b230 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
2b240 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b250 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
2b260 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2b270 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2b280 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2b290 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b2a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2b2b0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2b2c0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2b2d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2b2e0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2b2f0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2b300 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2b310 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2b320 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2b330 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2b340 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2b350 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2b360 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2b370 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2b380 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2b390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b3a0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2b3b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2b3c0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2b3d0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2b3e0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2b3f0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2b400 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2b410 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2b420 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2b430 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2b440 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2b450 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2b460 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
2b470 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
2b480 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
2b490 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
2b4a0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
2b4b0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
2b4c0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
2b4d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b4e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b4f0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b500 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b510 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2b520 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2b530 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b540 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2b550 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2b560 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b570 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2b580 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b590 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
2b5a0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
2b5b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b5c0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2b5d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b5e0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2b5f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b600 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2b610 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2b620 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2b630 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b640 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2b650 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2b660 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2b670 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2b680 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2b690 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2b6a0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2b6b0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2b6c0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2b6d0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2b6e0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2b6f0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2b700 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2b710 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2b720 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2b730 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2b740 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2b750 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2b760 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2b770 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2b780 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2b790 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2b7a0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2b7b0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2b7c0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2b7d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2b7e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2b7f0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2b800 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2b810 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2b820 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2b830 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2b840 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2b850 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2b860 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2b870 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2b880 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2b890 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2b8a0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2b8b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2b8c0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2b8d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2b8e0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2b8f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2b900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b910 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b920 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b940 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b950 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b960 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b970 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2b980 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b990 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b9a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2b9b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b9c0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2b9d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2b9e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b9f0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2ba00 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2ba10 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f  en Name.** METHO
2ba20 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ba30 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2ba40 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
2ba50 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
2ba60 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
2ba70 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
2ba80 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
2ba90 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
2baa0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
2bab0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2bac0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2bad0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
2bae0 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
2baf0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
2bb00 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
2bb10 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
2bb20 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
2bb30 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
2bb40 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
2bb50 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
2bb60 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
2bb70 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
2bb80 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
2bb90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bba0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2bbb0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2bbc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2bbd0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2bbe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2bbf0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2bc00 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2bc10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bc20 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  r_name()]..*/.in
2bc30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2bc40 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2bc50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2bc60 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2bc70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bc80 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2bc90 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2bca0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2bcb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2bcc0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
2bcd0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2bce0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2bcf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2bd00 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2bd10 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2bd20 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2bd30 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2bd40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bd50 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2bd60 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2bd70 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2bd80 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2bd90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2bda0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2bdb0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2bdc0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2bdd0 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2bde0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2bdf0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2be00 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2be10 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2be20 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2be30 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2be40 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2be50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2be60 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2be70 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2be80 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2be90 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2bea0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2beb0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2bec0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2bed0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2bee0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2bef0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2bf00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2bf10 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2bf20 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2bf30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2bf40 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2bf50 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2bf60 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2bf70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2bf80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2bf90 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2bfa0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2bfb0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2bfc0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2bfd0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2bfe0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2bff0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2c000 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2c010 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c020 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2c030 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2c040 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2c050 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2c060 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c070 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2c080 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2c090 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2c0a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2c0b0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2c0c0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2c0d0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2c0e0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2c0f0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2c100 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2c110 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2c120 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2c130 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2c140 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2c150 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2c160 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2c170 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2c180 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2c190 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2c1a0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2c1b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c1c0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2c1d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2c1e0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2c1f0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2c200 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2c210 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2c220 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2c230 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2c240 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2c250 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c260 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2c270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2c280 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2c290 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2c2a0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2c2b0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2c2c0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2c2d0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2c2e0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2c2f0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2c300 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2c310 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2c320 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2c330 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2c340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2c350 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2c360 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2c370 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2c380 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2c390 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2c3a0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2c3b0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2c3c0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2c3d0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2c3e0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2c3f0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2c400 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2c410 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2c420 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2c430 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
2c440 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c450 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c460 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
2c470 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2c480 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2c490 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c4a0 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2c4b0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2c4c0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2c4d0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2c4e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2c4f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2c500 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2c510 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2c520 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2c530 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2c540 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2c550 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2c560 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2c570 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2c580 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2c590 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2c5a0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2c5b0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2c5c0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2c5d0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2c5e0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2c5f0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2c600 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2c610 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2c620 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2c630 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2c640 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c650 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2c660 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2c670 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2c680 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2c690 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2c6a0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2c6b0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2c6c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c6d0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2c6e0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2c6f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c700 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2c710 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2c720 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2c730 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2c740 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2c750 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2c760 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2c770 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2c780 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2c790 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2c7a0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2c7b0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2c7c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2c7d0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2c7e0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2c7f0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2c800 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2c810 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2c820 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2c830 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2c840 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2c850 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2c860 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2c870 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2c880 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2c890 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2c8a0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2c8b0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2c8c0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2c8d0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2c8e0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2c8f0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2c900 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2c910 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2c920 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2c930 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2c940 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2c950 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2c960 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2c970 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2c980 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2c990 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2c9a0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2c9b0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2c9c0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2c9d0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2c9e0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2c9f0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2ca00 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2ca10 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2ca20 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2ca30 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2ca40 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2ca50 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2ca60 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2ca70 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2ca80 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2ca90 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2caa0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2cab0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2cac0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2cad0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2cae0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2caf0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2cb00 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2cb10 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2cb20 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2cb30 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2cb40 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2cb50 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2cb60 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2cb70 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2cb80 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2cb90 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2cba0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2cbb0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2cbc0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2cbd0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2cbe0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2cbf0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2cc00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2cc10 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2cc20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2cc30 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2cc40 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2cc50 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2cc60 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2cc70 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2cc80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2cc90 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2cca0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2ccb0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2ccc0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2ccd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2cce0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2ccf0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2cd00 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2cd10 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2cd20 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2cd30 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2cd40 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2cd50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2cd60 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2cd70 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2cd80 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2cd90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2cda0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2cdb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2cdc0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2cdd0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2cde0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2cdf0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2ce00 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2ce10 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2ce20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ce30 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2ce40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2ce50 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2ce60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ce70 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2ce80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2ce90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cea0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2ceb0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2cec0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2ced0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2cee0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2cef0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2cf00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cf10 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2cf20 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2cf30 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2cf40 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2cf50 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2cf60 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2cf70 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2cf80 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2cf90 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2cfa0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2cfb0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2cfc0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2cfd0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2cfe0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2cff0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2d000 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2d010 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2d020 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2d030 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2d040 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2d050 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2d060 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2d070 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2d080 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2d090 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2d0a0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2d0b0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2d0c0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2d0d0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2d0e0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2d0f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2d100 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2d110 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2d120 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2d130 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2d140 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2d150 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2d160 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2d170 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2d180 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2d190 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2d1a0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2d1b0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2d1c0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2d1d0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2d1e0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2d1f0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2d200 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2d210 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2d220 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2d230 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2d240 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2d250 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2d260 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2d270 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2d280 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2d290 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2d2a0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2d2b0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2d2c0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2d2d0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2d2e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2d2f0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2d300 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2d310 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2d320 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2d330 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
2d340 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d350 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2d360 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d370 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2d380 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2d390 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2d3a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2d3b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2d3c0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2d3d0 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2d3e0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d3f0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2d400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d410 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2d420 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2d430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2d440 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2d450 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d460 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2d470 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2d480 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2d490 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2d4a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d4b0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2d4c0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2d4d0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2d4e0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2d4f0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2d500 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2d510 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2d520 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2d530 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2d540 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2d550 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2d560 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2d570 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2d580 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2d590 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2d5a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d5b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2d5c0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2d5d0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2d5e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2d5f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2d600 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2d610 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2d620 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2d630 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2d640 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2d650 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2d660 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2d670 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2d680 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2d690 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2d6a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2d6b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2d6c0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2d6d0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2d6e0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2d6f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2d700 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2d710 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2d720 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2d730 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2d740 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2d750 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2d760 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2d770 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2d780 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2d790 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2d7a0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2d7b0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2d7c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2d7d0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2d7e0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2d7f0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2d800 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2d810 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2d820 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2d830 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2d840 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2d850 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2d860 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2d870 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2d880 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2d890 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2d8a0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2d8b0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2d8c0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2d8d0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2d8e0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2d8f0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2d900 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2d910 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2d920 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2d930 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2d940 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2d950 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2d960 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2d970 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2d980 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2d990 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2d9a0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2d9b0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2d9c0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2d9d0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2d9e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2d9f0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2da00 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2da10 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2da20 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2da30 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2da40 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2da50 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2da60 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2da70 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2da80 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2da90 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2daa0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2dab0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2dac0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2dad0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2dae0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2daf0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2db00 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2db10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2db20 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2db30 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2db40 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2db50 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2db60 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2db70 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2db80 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2db90 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2dba0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2dbb0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2dbc0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2dbd0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2dbe0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2dbf0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2dc00 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2dc10 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2dc20 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2dc30 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2dc40 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2dc50 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2dc60 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2dc70 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2dc80 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2dc90 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2dca0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2dcb0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2dcc0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2dcd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2dce0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2dcf0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2dd00 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2dd10 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2dd20 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2dd30 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2dd40 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2dd50 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2dd60 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2dd70 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2dd80 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2dd90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2dda0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2ddb0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2ddc0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2ddd0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2dde0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2ddf0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2de00 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2de10 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2de20 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2de30 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2de40 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2de50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2de60 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2de70 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2de80 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2de90 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2dea0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2deb0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2dec0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2ded0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2dee0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2def0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2df00 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2df10 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2df20 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2df30 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2df40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2df50 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2df60 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2df70 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2df80 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2df90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2dfa0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2dfb0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2dfc0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2dfd0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2dfe0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2dff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2e000 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2e010 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2e020 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2e030 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2e040 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2e050 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2e060 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2e070 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2e080 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2e090 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2e0a0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2e0b0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2e0c0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2e0d0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2e0e0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2e0f0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2e100 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2e110 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2e120 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2e130 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2e140 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2e150 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2e160 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2e170 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2e180 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2e190 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2e1a0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2e1b0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2e1c0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2e1d0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2e1e0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2e1f0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2e200 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2e210 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2e220 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2e230 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2e240 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2e250 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2e260 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2e270 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2e280 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2e290 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2e2a0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2e2b0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2e2c0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2e2d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2e2e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e2f0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2e300 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2e310 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2e320 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2e330 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2e340 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2e350 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2e360 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2e370 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2e380 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2e390 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2e3a0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2e3b0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2e3c0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2e3d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2e3e0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2e3f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2e400 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2e410 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2e420 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2e430 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2e440 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2e450 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2e460 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2e470 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2e480 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2e490 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2e4a0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2e4b0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2e4c0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2e4d0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2e4e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2e4f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e500 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2e510 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2e520 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2e530 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2e540 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
2e550 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2e560 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e570 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2e580 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2e590 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e5a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2e5b0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2e5c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2e5d0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2e5e0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2e5f0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2e600 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2e610 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2e620 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2e630 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2e640 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2e650 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2e660 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2e670 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2e680 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2e690 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2e6a0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2e6b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e6c0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2e6d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2e6e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e6f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2e700 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2e710 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2e720 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2e730 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2e740 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2e750 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2e760 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2e770 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e780 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2e790 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2e7a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2e7b0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2e7c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2e7d0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2e7e0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2e7f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2e800 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2e810 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2e820 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2e830 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2e840 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2e850 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2e860 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2e870 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2e880 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2e890 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2e8a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2e8b0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2e8c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2e8d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e8e0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2e8f0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2e900 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2e910 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2e920 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2e930 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2e940 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2e950 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2e960 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2e970 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2e980 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2e990 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2e9a0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2e9b0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2e9c0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2e9d0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2e9e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2e9f0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2ea00 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2ea10 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2ea20 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2ea30 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2ea40 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2ea50 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2ea60 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2ea70 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2ea80 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2ea90 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2eaa0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2eab0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2eac0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2ead0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2eae0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2eaf0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2eb00 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2eb10 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2eb20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2eb30 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2eb40 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2eb50 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2eb60 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2eb70 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2eb80 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2eb90 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2eba0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2ebb0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2ebc0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2ebd0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2ebe0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2ebf0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2ec00 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2ec10 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2ec20 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
2ec30 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ec40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ec50 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2ec60 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2ec70 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2ec80 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2ec90 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2eca0 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2ecb0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2ecc0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2ecd0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2ece0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ecf0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2ed00 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2ed10 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2ed20 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2ed30 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2ed40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ed50 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2ed60 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2ed70 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2ed80 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2ed90 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2eda0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2edb0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2edc0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2edd0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2ede0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2edf0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2ee00 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2ee10 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2ee20 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2ee30 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2ee40 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2ee50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2ee60 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2ee70 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2ee80 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2ee90 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2eea0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2eeb0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2eec0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2eed0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2eee0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2eef0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2ef00 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2ef10 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2ef20 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2ef30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2ef40 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2ef50 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2ef60 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2ef70 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2ef80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2ef90 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2efa0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2efb0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2efc0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2efd0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2efe0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2eff0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2f000 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f010 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2f020 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2f030 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2f040 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2f050 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2f060 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2f070 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2f080 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f090 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2f0a0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2f0b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2f0c0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2f0d0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2f0e0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2f0f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2f100 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2f110 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2f120 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2f130 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f140 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2f150 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2f160 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2f170 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2f180 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2f190 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2f1a0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2f1b0 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2f1c0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2f1d0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2f1e0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2f1f0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2f200 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2f210 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2f220 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2f230 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2f240 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2f250 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2f260 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2f270 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2f280 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2f290 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2f2a0 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2f2b0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2f2c0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2f2d0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2f2e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f2f0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2f300 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2f310 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2f320 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2f330 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2f340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f350 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2f360 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f370 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2f380 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2f390 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2f3a0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2f3b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f3c0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2f3d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f3e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2f3f0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2f400 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2f410 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2f420 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2f430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f440 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2f450 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2f460 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2f470 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2f480 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2f490 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2f4a0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2f4b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f4c0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2f4d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2f4e0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2f4f0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2f500 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2f510 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2f520 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f530 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2f540 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2f550 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2f560 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2f570 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2f580 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2f590 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f5a0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2f5b0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2f5c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f5d0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2f5e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2f5f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f600 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2f610 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2f620 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f630 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2f640 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2f650 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2f660 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2f670 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2f680 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2f690 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f6a0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2f6b0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2f6c0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2f6d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f6e0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2f6f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2f700 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2f710 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2f720 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
2f730 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2f740 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f750 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2f760 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f770 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2f780 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f790 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
2f7a0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
2f7b0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2f7c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2f7d0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2f7e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2f7f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2f800 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
2f810 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2f820 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
2f830 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
2f840 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
2f850 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
2f860 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2f870 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f880 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2f890 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f8a0 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
2f8b0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
2f8c0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
2f8d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2f8e0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
2f8f0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
2f900 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f910 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
2f920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f930 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
2f940 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
2f950 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
2f960 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
2f970 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
2f980 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
2f990 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
2f9a0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2f9b0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
2f9c0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
2f9d0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
2f9e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2f9f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2fa00 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2fa10 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2fa20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2fa30 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
2fa40 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
2fa50 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
2fa60 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2fa70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2fa80 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
2fa90 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
2faa0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2fab0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2fac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2fad0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2fae0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2faf0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2fb00 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2fb10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2fb20 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2fb30 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2fb40 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2fb50 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2fb60 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2fb70 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2fb80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fb90 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2fba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2fbb0 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
2fbc0 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
2fbd0 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
2fbe0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2fbf0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2fc00 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2fc10 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2fc20 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2fc30 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2fc40 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2fc50 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2fc60 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2fc70 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2fc80 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2fc90 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2fca0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2fcb0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2fcc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2fcd0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2fce0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2fcf0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2fd00 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2fd10 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2fd20 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2fd30 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2fd40 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2fd50 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2fd60 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2fd70 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2fd80 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2fd90 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2fda0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2fdb0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2fdc0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2fdd0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2fde0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2fdf0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2fe00 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2fe10 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2fe20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2fe30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2fe40 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2fe50 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2fe60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2fe70 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2fe80 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2fe90 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2fea0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2feb0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2fec0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2fed0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2fee0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2fef0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2ff00 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2ff10 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2ff20 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2ff30 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2ff40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2ff50 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2ff60 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2ff70 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2ff80 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2ff90 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2ffa0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2ffb0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2ffc0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2ffd0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2ffe0 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
2fff0 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
30000 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30010 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
30020 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
30030 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
30040 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
30050 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
30060 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
30070 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
30080 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
30090 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
300a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
300b0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
300c0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
300d0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
300e0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
300f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
30100 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
30110 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
30120 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
30130 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
30140 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
30150 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
30160 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
30170 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
30180 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
30190 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
301a0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
301b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
301c0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
301d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
301e0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
301f0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
30200 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
30210 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
30220 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
30230 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
30240 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
30250 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
30260 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
30270 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
30280 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
30290 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
302a0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
302b0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
302c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
302d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
302e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
302f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
30300 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
30310 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
30320 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
30330 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
30340 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
30350 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
30360 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
30370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
30380 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
30390 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
303a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
303b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
303c0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
303d0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
303e0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
303f0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
30400 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30410 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
30420 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30430 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
30440 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30450 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
30460 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
30470 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
30480 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
30490 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
304a0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
304b0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
304c0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
304d0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
304e0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
304f0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
30500 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
30510 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
30520 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
30530 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
30540 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
30550 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
30560 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
30570 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
30580 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
30590 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
305a0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
305b0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
305c0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
305d0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
305e0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
305f0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
30600 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
30610 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
30620 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
30630 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
30640 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
30650 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
30660 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
30670 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
30680 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
30690 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
306a0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
306b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
306c0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
306d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
306e0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
306f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30700 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
30710 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
30720 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
30730 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
30740 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30750 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
30760 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
30770 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
30780 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
30790 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
307a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
307b0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
307c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
307d0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
307e0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
307f0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
30800 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
30810 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
30820 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
30830 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30840 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
30850 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
30860 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
30870 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
30880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30890 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
308a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
308b0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
308c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
308d0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
308e0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
308f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
30900 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
30910 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
30920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30930 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
30940 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
30950 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
30960 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
30970 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
30980 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
30990 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
309a0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
309b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
309c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
309d0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
309e0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
309f0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
30a00 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
30a10 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
30a20 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
30a30 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
30a40 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
30a50 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
30a60 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
30a70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
30a80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30a90 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
30aa0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
30ab0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
30ac0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
30ad0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
30ae0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
30af0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
30b00 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
30b10 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
30b20 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
30b30 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
30b40 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
30b50 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
30b60 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
30b70 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
30b80 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
30b90 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
30ba0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
30bb0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
30bc0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
30bd0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
30be0 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
30bf0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30c00 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
30c10 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
30c20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
30c30 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
30c40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30c50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
30c60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
30c70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30c80 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
30c90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
30ca0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
30cb0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
30cc0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
30cd0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
30ce0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
30cf0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
30d00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
30d10 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30d20 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
30d30 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
30d40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30d50 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
30d60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
30d70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30d80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30d90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30da0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
30db0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
30dc0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
30dd0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
30de0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
30df0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
30e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30e10 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
30e20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
30e30 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
30e40 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
30e50 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
30e60 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30e70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
30e80 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
30e90 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
30ea0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
30eb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
30ec0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
30ed0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
30ee0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
30ef0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
30f00 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
30f10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30f20 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
30f30 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
30f40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
30f50 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
30f60 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
30f70 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
30f80 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
30f90 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
30fa0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
30fb0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
30fc0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
30fd0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
30fe0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
30ff0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
31000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
31010 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
31020 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
31030 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
31040 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
31050 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
31060 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
31070 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
31080 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
31090 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
310a0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
310b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
310c0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
310d0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
310e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
310f0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
31100 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
31110 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
31120 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
31130 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
31140 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
31150 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
31160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
31170 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
31180 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
31190 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
311a0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
311b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
311c0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
311d0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
311e0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
311f0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
31200 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
31210 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
31220 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
31230 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
31240 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
31250 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
31260 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
31270 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
31280 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
31290 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
312a0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
312b0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
312c0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
312d0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
312e0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
312f0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
31300 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
31310 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
31320 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31330 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
31340 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
31350 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
31360 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31370 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
31380 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
31390 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
313a0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
313b0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
313c0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
313d0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
313e0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
313f0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
31400 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
31410 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
31420 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
31430 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
31440 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
31450 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
31460 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
31470 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
31480 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
31490 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
314a0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
314b0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
314c0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
314d0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
314e0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
314f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31500 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
31510 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
31520 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
31530 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
31540 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
31550 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
31560 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
31570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31580 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
31590 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
315a0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
315b0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
315c0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
315d0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
315e0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
315f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
31600 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
31610 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
31620 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
31630 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
31640 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
31650 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
31660 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
31670 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
31680 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
31690 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
316a0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
316b0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
316c0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
316d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
316e0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
316f0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
31700 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
31710 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
31720 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
31730 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31740 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
31750 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
31760 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
31770 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31780 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
31790 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
317a0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
317b0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
317c0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
317d0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
317e0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
317f0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
31800 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
31810 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
31820 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
31830 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
31840 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
31850 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
31860 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
31870 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
31880 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
31890 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
318a0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
318b0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
318c0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
318d0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
318e0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
318f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
31900 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
31910 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
31920 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
31930 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
31940 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
31950 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
31960 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
31970 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
31980 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
31990 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
319a0 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
319b0 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
319c0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
319d0 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
319e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
319f0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
31a00 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
31a10 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
31a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31a30 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
31a40 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
31a50 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
31a60 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
31a70 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
31a80 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
31a90 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
31aa0 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
31ab0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31ac0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
31ad0 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
31ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31af0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
31b00 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
31b10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
31b20 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
31b30 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
31b40 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
31b50 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
31b60 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
31b70 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
31b80 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
31b90 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
31ba0 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
31bb0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
31bc0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
31bd0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
31be0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
31bf0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
31c00 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
31c10 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
31c20 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
31c30 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
31c40 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
31c50 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
31c60 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
31c70 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
31c80 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
31c90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
31ca0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
31cb0 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
31cc0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
31cd0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
31ce0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
31cf0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
31d00 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
31d10 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
31d20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
31d30 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
31d40 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
31d50 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
31d60 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
31d70 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
31d80 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
31d90 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
31da0 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
31db0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
31dc0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
31dd0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
31de0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
31df0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
31e00 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
31e10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
31e20 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
31e30 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
31e40 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
31e50 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
31e60 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
31e70 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
31e80 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
31e90 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
31ea0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
31eb0 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
31ec0 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
31ed0 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
31ee0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
31ef0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
31f00 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
31f10 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
31f20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
31f30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
31f40 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
31f50 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
31f60 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
31f70 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
31f80 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
31f90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
31fa0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31fb0 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
31fc0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
31fd0 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
31fe0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
31ff0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
32000 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
32010 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
32020 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
32030 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
32040 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
32050 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
32060 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
32070 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
32080 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
32090 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
320a0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
320b0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
320c0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
320d0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
320e0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
320f0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
32100 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
32110 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
32120 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
32130 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
32140 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
32150 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
32160 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
32170 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
32180 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
32190 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
321a0 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
321b0 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
321c0 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
321d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
321e0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
321f0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
32200 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
32210 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
32220 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
32230 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
32240 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
32250 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
32260 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
32270 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
32280 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
32290 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
322a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
322b0 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
322c0 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
322d0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
322e0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
322f0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
32300 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
32310 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
32320 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
32330 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
32340 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
32350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32360 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
32370 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
32380 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
32390 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
323a0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
323b0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
323c0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
323d0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
323e0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
323f0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
32400 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
32410 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
32420 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
32430 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
32440 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32450 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
32460 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32470 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32480 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
32490 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
324a0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
324b0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
324c0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
324d0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
324e0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
324f0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
32500 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
32510 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32520 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
32530 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
32540 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
32550 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
32560 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
32570 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
32580 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
32590 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
325a0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
325b0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
325c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
325d0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
325e0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
325f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32600 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
32610 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
32620 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
32630 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
32640 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
32650 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
32660 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
32670 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
32680 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
32690 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
326a0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
326b0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
326c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
326d0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
326e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
326f0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
32700 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
32710 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32720 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
32730 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
32740 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
32750 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
32760 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
32770 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
32780 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
32790 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
327a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
327b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
327c0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
327d0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
327e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
327f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32800 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
32810 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
32820 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
32830 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
32840 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
32850 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
32860 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
32870 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
32880 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
32890 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
328a0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
328b0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
328c0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
328d0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
328e0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
328f0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
32900 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
32910 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
32920 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
32930 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
32940 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32950 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
32960 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
32970 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
32980 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
32990 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
329a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
329b0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
329c0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
329d0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
329e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
329f0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
32a00 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
32a10 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
32a20 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
32a30 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
32a40 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
32a50 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
32a60 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
32a70 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
32a80 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
32a90 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
32aa0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
32ab0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
32ac0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
32ad0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
32ae0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
32af0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
32b00 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
32b10 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
32b20 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
32b30 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
32b40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32b50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
32b60 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
32b70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32b80 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
32b90 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
32ba0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
32bb0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
32bc0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
32bd0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
32be0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
32bf0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
32c00 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
32c10 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
32c20 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
32c30 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
32c40 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
32c50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32c60 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
32c70 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
32c80 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
32c90 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
32ca0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32cb0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
32cc0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
32cd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32ce0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32cf0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32d00 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
32d10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32d20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32d30 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
32d40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
32d50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32d60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32d70 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32d80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
32d90 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
32da0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
32db0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
32dc0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
32dd0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
32de0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32df0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32e00 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
32e10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32e20 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32e30 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32e40 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
32e50 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
32e60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32e70 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
32e80 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
32e90 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
32ea0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32eb0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32ec0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
32ed0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
32ee0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32ef0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32f00 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32f10 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
32f20 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32f30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32f40 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
32f50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32f60 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
32f70 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
32f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32f90 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
32fa0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32fb0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
32fc0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
32fd0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
32fe0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
32ff0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
33000 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
33010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
33020 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
33030 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
33040 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
33050 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
33060 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
33070 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
33080 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
33090 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
330a0 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
330b0 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
330c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
330d0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
330e0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
330f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
33100 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33110 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
33120 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
33130 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
33140 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
33150 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
33160 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33170 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
33180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
33190 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
331a0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
331b0 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
331c0 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
331d0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
331e0 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
331f0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
33200 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
33210 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
33220 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33230 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
33240 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
33250 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33260 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33270 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
33280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
33290 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
332a0 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
332b0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
332c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
332d0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
332e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
332f0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
33300 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
33310 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
33320 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
33330 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
33340 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
33350 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
33360 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
33370 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
33380 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
33390 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
333a0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
333b0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
333c0 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
333d0 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
333e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
333f0 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
33400 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
33410 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
33420 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
33430 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
33440 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
33450 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
33460 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33470 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
33480 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
33490 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
334a0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
334b0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
334c0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
334d0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
334e0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
334f0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
33500 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
33510 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
33520 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
33530 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
33540 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
33550 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
33560 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
33570 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
33580 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
33590 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
335a0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
335b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
335c0 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
335d0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
335e0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
335f0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
33600 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
33610 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
33620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
33630 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
33640 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
33650 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
33660 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
33670 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
33680 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
33690 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
336a0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
336b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
336c0 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a   aggregate.  .**
336d0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
336e0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
336f0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
33700 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
33710 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
33720 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33730 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
33740 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33750 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
33760 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
33770 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
33780 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
33790 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
337a0 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
337b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
337c0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
337d0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
337e0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
337f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33800 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
33810 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
33820 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33830 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
33840 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
33850 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
33860 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
33870 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
33880 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
33890 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
338a0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
338b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
338c0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
338d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
338e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
338f0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
33900 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
33910 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
33920 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
33930 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
33940 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
33950 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
33960 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
33970 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
33980 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
33990 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
339a0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
339b0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
339c0 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
339d0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
339e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
339f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33a00 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
33a10 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
33a20 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
33a30 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
33a40 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
33a50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33a60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
33a70 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
33a80 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
33a90 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
33aa0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
33ab0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
33ac0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
33ad0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33ae0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
33af0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
33b00 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
33b10 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
33b20 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
33b30 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
33b40 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
33b50 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
33b60 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
33b70 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
33b80 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
33b90 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
33ba0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
33bb0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
33bc0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
33bd0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
33be0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
33bf0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
33c00 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
33c10 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
33c20 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
33c30 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
33c40 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
33c50 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
33c60 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
33c70 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
33c80 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
33c90 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
33ca0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
33cb0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
33cc0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
33cd0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
33ce0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
33cf0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
33d00 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
33d10 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
33d20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
33d30 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
33d40 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
33d50 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
33d60 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
33d70 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
33d80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
33d90 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
33da0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
33db0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
33dc0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
33dd0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
33de0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
33df0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
33e00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
33e10 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
33e20 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
33e30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33e40 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
33e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33e60 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
33e70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
33e80 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
33e90 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
33ea0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
33eb0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
33ec0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
33ed0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
33ee0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
33ef0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
33f00 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
33f10 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
33f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33f30 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
33f40 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
33f50 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
33f60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
33f70 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
33f80 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
33f90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33fa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
33fb0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
33fc0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
33fd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
33fe0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
33ff0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
34000 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
34010 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
34020 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
34030 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
34040 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34060 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34070 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34080 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
34090 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
340a0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
340b0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
340c0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
340d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
340e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
340f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
34100 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
34110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34130 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75  : Finding The Su
34140 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c  btype Of SQL Val
34150 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
34160 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
34170 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
34180 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20  alue_subtype(V) 
34190 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
341a0 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
341b0 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74  .** an [applicat
341c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
341d0 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65  function] argume
341e0 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79  nt V.  The subty
341f0 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  pe.** informatio
34200 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
34210 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20   pass a limited 
34220 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78  amount of contex
34230 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51  t from.** one SQ
34240 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e  L function to an
34250 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20  other.  Use the 
34260 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34270 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f  subtype()].** ro
34280 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65  utine to set the
34290 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65   subtype for the
342a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
342b0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
342c0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
342d0 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73  akes no use of s
342e0 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20  ubtype itself.  
342f0 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73  It merely passes
34300 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   the subtype.** 
34310 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20  from the result 
34320 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74  of one [applicat
34330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
34340 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74  function] into t
34350 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61  he.** input of a
34360 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67  nother..*/.unsig
34370 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  ned int sqlite3_
34380 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71  value_subtype(sq
34390 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
343a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
343b0 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
343c0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
343d0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
343e0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
343f0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
34400 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
34410 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34420 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
34430 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
34440 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
34450 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
34460 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
34470 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
34480 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
34490 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
344a0 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
344b0 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
344c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
344d0 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
344e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
344f0 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
34500 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
34510 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
34520 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
34530 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
34540 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
34550 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
34560 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34570 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
34580 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
34590 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
345a0 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61  ()].  ^If V is a
345b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
345c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61   then sqlite3_va
345d0 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61  lue_free(V) is a
345e0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
345f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
34600 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f  IMENTAL sqlite3_
34610 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76  value *sqlite3_v
34620 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73  alue_dup(const s
34630 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34640 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
34650 54 41 4c 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TAL void sqlite3
34660 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69  _value_free(sqli
34670 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
34680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
34690 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
346a0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
346b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
346c0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
346d0 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
346e0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
346f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
34700 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
34710 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
34720 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
34730 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
34740 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
34750 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
34760 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34770 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
34780 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
34790 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
347a0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
347b0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
347c0 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
347d0 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
347e0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
347f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
34800 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
34810 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
34820 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
34830 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
34840 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34850 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
34860 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
34870 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
34880 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
34890 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
348a0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
348b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
348c0 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
348d0 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
348e0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
348f0 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
34900 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
34910 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
34920 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
34930 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
34940 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
34950 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
34960 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
34970 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
34980 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
34990 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
349a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
349b0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
349c0 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
349d0 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
349e0 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
349f0 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
34a00 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34a10 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
34a20 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
34a30 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
34a40 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
34a50 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
34a60 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34a70 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
34a80 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
34a90 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
34aa0 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
34ab0 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
34ac0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
34ad0 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
34ae0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
34af0 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
34b00 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
34b10 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
34b20 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
34b30 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34b40 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
34b50 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
34b60 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
34b70 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
34b80 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
34b90 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
34ba0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
34bb0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
34bc0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
34bd0 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
34be0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
34bf0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
34c00 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
34c10 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
34c20 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
34c30 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
34c40 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
34c50 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
34c60 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
34c70 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
34c80 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
34c90 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
34ca0 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
34cb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
34cc0 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
34cd0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
34ce0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
34cf0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
34d00 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
34d10 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
34d20 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
34d30 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
34d40 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
34d50 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
34d60 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
34d70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
34d80 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
34d90 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
34da0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
34db0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
34dc0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
34dd0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
34de0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
34df0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
34e00 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
34e10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34e20 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
34e30 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34e40 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
34e50 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
34e60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
34e70 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
34e80 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
34e90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
34ea0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34eb0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
34ec0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
34ed0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
34ee0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
34ef0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
34f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34f10 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
34f20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34f30 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
34f40 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
34f50 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
34f60 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
34f70 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
34f80 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
34f90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34fa0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
34fb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34fc0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
34fd0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
34fe0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
34ff0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
35000 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
35010 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
35020 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
35030 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
35040 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
35050 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
35060 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35070 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
35080 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
35090 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
350a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
350b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
350c0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
350d0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
350e0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
350f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
35100 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35110 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
35120 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
35130 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
35140 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
35150 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
35160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
35170 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
35180 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
35190 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
351a0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
351b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
351c0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
351d0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
351e0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
351f0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
35200 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
35210 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
35220 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
35230 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
35240 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
35250 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35260 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
35270 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48  ary Data.** METH
35280 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
35290 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ext.**.** These 
352a0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
352b0 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
352c0 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
352d0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
352e0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
352f0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
35300 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
35310 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
35320 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
35330 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
35340 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
35350 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
35360 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
35370 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
35380 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
35390 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
353a0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
353b0 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
353c0 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
353d0 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
353e0 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
353f0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
35400 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
35410 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
35420 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
35430 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
35440 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
35450 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
35460 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
35470 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
35480 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
35490 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
354a0 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
354b0 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
354c0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
354d0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
354e0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
354f0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
35500 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
35510 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
35520 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35530 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
35540 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35550 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
35560 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
35570 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
35580 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35590 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
355a0 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
355b0 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
355c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
355d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
355e0 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
355f0 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
35600 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
35610 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
35620 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
35630 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
35640 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
35650 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
35660 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
35670 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35680 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
35690 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
356a0 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
356b0 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
356c0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
356d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
356e0 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
356f0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
35700 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
35710 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
35720 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
35730 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
35740 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35750 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
35760 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
35770 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
35780 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
35790 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
357a0 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
357b0 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
357c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
357d0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
357e0 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
357f0 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
35800 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
35810 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
35820 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
35830 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
35840 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
35850 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
35860 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
35870 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
35880 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
35890 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
358a0 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
358b0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
358c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
358d0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
358e0 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
358f0 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
35900 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
35910 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
35920 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
35930 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
35940 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
35950 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
35960 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35970 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
35980 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
35990 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
359a0 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
359b0 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
359c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
359d0 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
359e0 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
359f0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
35a00 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
35a10 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
35a20 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
35a30 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
35a40 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
35a50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35a60 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
35a70 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
35a80 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
35a90 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
35aa0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
35ab0 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
35ac0 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
35ad0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35ae0 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
35af0 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
35b00 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
35b10 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35b20 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
35b30 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
35b40 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
35b50 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
35b60 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
35b70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35b80 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
35b90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
35ba0 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
35bb0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
35bc0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
35bd0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
35be0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
35bf0 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
35c00 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
35c10 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
35c20 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
35c30 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
35c40 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
35c50 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
35c60 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
35c70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
35c80 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
35c90 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
35ca0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
35cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
35cc0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
35cd0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
35ce0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
35cf0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
35d00 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
35d10 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
35d20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
35d30 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
35d40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
35d50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
35d60 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
35d70 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
35d80 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
35d90 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
35da0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
35db0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
35dc0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
35dd0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
35de0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
35df0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
35e00 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
35e10 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
35e20 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
35e30 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
35e40 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
35e50 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
35e60 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
35e70 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
35e80 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
35e90 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
35ea0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
35eb0 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
35ec0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
35ed0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
35ee0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
35ef0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
35f00 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
35f10 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
35f20 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
35f30 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
35f40 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
35f50 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
35f60 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
35f70 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
35f80 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
35f90 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
35fa0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
35fb0 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70  ompilers..*/.typ
35fc0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
35fd0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
35fe0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
35ff0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
36000 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
36010 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
36020 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
36030 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
36040 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
36050 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
36060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
36070 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
36080 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
36090 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  tion.** METHOD: 
360a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
360b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
360c0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
360d0 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
360e0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
360f0 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
36100 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
36110 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
36120 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
36130 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
36140 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36150 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36160 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
36170 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
36180 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
36190 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
361a0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
361b0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
361c0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
361d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
361e0 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
361f0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
36200 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
36210 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
36220 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
36230 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
36240 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
36250 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
36260 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
36270 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36280 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
36290 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
362a0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
362b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
362c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
362d0 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
362e0 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
362f0 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
36300 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
36310 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
36320 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
36330 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
36340 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
36350 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36360 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43  esult_zeroblob(C
36370 2c 4e 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ,N) and sqlite3_
36380 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36  result_zeroblob6
36390 34 28 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66  4(C,N).** interf
363a0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
363b0 75 6c 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ult of the appli
363c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
363d0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
363e0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
363f0 6e 67 20 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65  ng all zero byte
36400 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
36410 20 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   size..**.** ^Th
36420 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36430 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
36440 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
36450 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
36460 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36470 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36480 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
36490 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
364a0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
364b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
364c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
364d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
364e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
364f0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
36500 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
36510 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
36520 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
36530 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
36540 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
36550 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
36560 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
36570 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
36580 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
36590 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
365a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
365b0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
365c0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
365d0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
365e0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
365f0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
36600 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
36610 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36620 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
36630 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
36640 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
36650 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
36660 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
36670 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
36680 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
36690 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
366a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
366b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
366c0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
366d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
366e0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
366f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
36700 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
36710 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
36720 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
36730 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
36740 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
36750 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
36760 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
36770 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
36780 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
36790 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
367a0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
367b0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
367c0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
367d0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
367e0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
367f0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
36800 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
36810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36820 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
36830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36840 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
36850 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
36860 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
36870 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
36880 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
36890 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
368a0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
368b0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
368c0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
368d0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
368e0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
368f0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
36900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36910 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
36920 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
36930 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
36940 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
36950 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
36960 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
36970 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
36980 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
36990 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
369a0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
369b0 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
369c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
369d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
369e0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
369f0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
36a00 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
36a10 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
36a20 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
36a30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36a40 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  or_toobig() inte
36a50 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36a60 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
36a70 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
36a80 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
36a90 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
36aa0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
36ab0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36ac0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36ad0 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ror_nomem() inte
36ae0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36af0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
36b00 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
36b10 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
36b20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
36b30 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
36b40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
36b50 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
36b60 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36b70 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36b80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36b90 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36ba0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
36bb0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
36bc0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
36bd0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
36be0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36bf0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
36c00 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36c10 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36c20 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
36c30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36c40 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
36c50 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
36c60 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36c70 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36c80 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36c90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36ca0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
36cb0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36cc0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
36cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36ce0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36cf0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
36d00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36d10 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
36d20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36d30 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
36d40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
36d50 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
36d60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36d70 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
36d80 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
36d90 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
36da0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36db0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36dc0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
36dd0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
36de0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
36df0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
36e00 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
36e10 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
36e20 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
36e30 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
36e40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65  ctively..** ^The
36e50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36e60 74 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61  text64() interfa
36e70 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36e80 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a  rn value of an.*
36e90 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  * application-de
36ea0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36eb0 6f 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69  o be a text stri
36ec0 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e  ng in an encodin
36ed0 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62  g.** specified b
36ee0 79 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64  y the fifth (and
36ef0 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72   last) parameter
36f00 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20  , which must be 
36f10 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54  one.** of [SQLIT
36f20 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
36f30 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
36f40 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
36f50 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a  QLITE_UTF16LE]..
36f60 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
36f70 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
36f80 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
36f90 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
36fa0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
36fb0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
36fc0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36fd0 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
36fe0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36ff0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
37000 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
37010 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
37020 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
37030 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
37040 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
37050 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
37060 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
37070 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
37080 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
37090 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
370a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
370b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
370c0 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
370d0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
370e0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
370f0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
37100 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
37110 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
37120 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
37130 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
37140 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
37150 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
37160 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
37170 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
37180 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
37190 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
371a0 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
371b0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
371c0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
371d0 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
371e0 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
371f0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
37200 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
37210 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
37220 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
37230 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
37240 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
37250 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
37260 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
37270 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
37280 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
37290 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
372a0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
372b0 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
372c0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
372d0 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
372e0 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
372f0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
37300 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
37310 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
37320 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
37330 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
37340 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
37350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
37360 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
37370 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
37380 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
37390 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
373a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
373b0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
373c0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
373d0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
373e0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
373f0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
37400 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
37410 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
37420 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
37430 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
37440 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
37450 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
37460 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
37470 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
37480 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
37490 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
374a0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
374b0 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
374c0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
374d0 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
374e0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
374f0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
37500 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
37510 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
37520 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
37530 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
37540 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
37550 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
37560 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37570 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
37580 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
37590 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
375a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
375b0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
375c0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
375d0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
375e0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
375f0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
37600 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
37610 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37620 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
37630 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
37640 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37650 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
37660 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
37670 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
37680 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37690 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
376a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
376b0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
376c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
376d0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
376e0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
376f0 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
37700 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37710 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
37720 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
37730 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
37740 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
37750 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
37760 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
37770 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
37780 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
37790 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
377a0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
377b0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
377c0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
377d0 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
377e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
377f0 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
37800 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
37810 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
37820 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
37830 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
37840 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
37850 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
37860 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37870 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
37880 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
37890 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
378a0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
378b0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
378c0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
378d0 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
378e0 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
378f0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
37900 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37910 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
37920 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
37930 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
37940 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
37950 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
37960 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37970 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
37980 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37990 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
379a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
379b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
379c0 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  lt_blob64(sqlite
379d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74  3_context*,const
379e0 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20   void*,.        
379f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37a00 20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36     sqlite3_uint6
37a10 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  4,void(*)(void*)
37a20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37a30 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
37a40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37a50 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
37a60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37a70 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
37a80 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37a90 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
37aa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37ab0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
37ac0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37ad0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
37ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37af0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
37b00 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
37b10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37b20 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
37b30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
37b40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37b50 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
37b60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37b70 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
37b80 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
37b90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37ba0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
37bb0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
37bc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37bd0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
37be0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37bf0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
37c00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
37c10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37c20 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
37c30 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37c40 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
37c50 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
37c60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37c70 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
37c80 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37c90 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
37ca0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
37cb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37cc0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
37cd0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
37ce0 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73  ncoding);.void s
37cf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37d00 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
37d10 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
37d20 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
37d30 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
37d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37d50 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
37d60 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37d70 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
37d80 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
37d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37da0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
37db0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37dc0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
37dd0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37de0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37df0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
37e00 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
37e10 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
37e20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
37e30 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
37e40 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
37e50 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 75  int sqlite3_resu
37e60 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  lt_zeroblob64(sq
37e70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37e80 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 6e  sqlite3_uint64 n
37e90 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
37ea0 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
37eb0 20 53 75 62 74 79 70 65 20 4f 66 20 41 6e 20 53   Subtype Of An S
37ec0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d  QL Function.** M
37ed0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
37ee0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65  ontext.**.** The
37ef0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37f00 73 75 62 74 79 70 65 28 43 2c 54 29 20 66 75 6e  subtype(C,T) fun
37f10 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
37f20 20 73 75 62 74 79 70 65 20 6f 66 0a 2a 2a 20 74   subtype of.** t
37f30 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  he result from t
37f40 68 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  he [application-
37f50 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37f60 74 69 6f 6e 5d 20 77 69 74 68 20 0a 2a 2a 20 5b  tion] with .** [
37f70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
37f80 20 43 20 74 6f 20 62 65 20 74 68 65 20 76 61 6c   C to be the val
37f90 75 65 20 54 2e 20 20 4f 6e 6c 79 20 74 68 65 20  ue T.  Only the 
37fa0 6c 6f 77 65 72 20 38 20 62 69 74 73 20 0a 2a 2a  lower 8 bits .**
37fb0 20 6f 66 20 74 68 65 20 73 75 62 74 79 70 65 20   of the subtype 
37fc0 54 20 61 72 65 20 70 72 65 73 65 72 76 65 64 20  T are preserved 
37fd0 69 6e 20 63 75 72 72 65 6e 74 20 76 65 72 73 69  in current versi
37fe0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 3b 0a 2a  ons of SQLite;.*
37ff0 2a 20 68 69 67 68 65 72 20 6f 72 64 65 72 20 62  * higher order b
38000 69 74 73 20 61 72 65 20 64 69 73 63 61 72 64 65  its are discarde
38010 64 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72  d..** The number
38020 20 6f 66 20 73 75 62 74 79 70 65 20 62 79 74 65   of subtype byte
38030 73 20 70 72 65 73 65 72 76 65 64 20 62 79 20 53  s preserved by S
38040 51 4c 69 74 65 20 6d 69 67 68 74 20 69 6e 63 72  QLite might incr
38050 65 61 73 65 0a 2a 2a 20 69 6e 20 66 75 74 75 72  ease.** in futur
38060 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
38070 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  Lite..*/.void sq
38080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
38090 74 79 70 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  type(sqlite3_con
380a0 74 65 78 74 2a 2c 75 6e 73 69 67 6e 65 64 20 69  text*,unsigned i
380b0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
380c0 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
380d0 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
380e0 6e 63 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  nces.** METHOD: 
380f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
38100 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
38110 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
38120 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
38130 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
38140 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
38150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38160 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
38170 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38180 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
38190 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
381a0 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
381b0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
381c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
381d0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
381e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
381f0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
38200 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
38210 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
38220 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
38230 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38240 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
38250 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
38260 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
38270 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
38280 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
38290 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
382a0 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
382b0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
382c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
382d0 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
382e0 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
382f0 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
38300 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
38310 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
38320 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
38330 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
38340 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
38350 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
38360 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
38370 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
38380 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
38390 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
383a0 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
383b0 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
383c0 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
383d0 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
383e0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
383f0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
38400 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
38410 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
38420 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
38430 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
38440 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
38450 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
38460 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
38470 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
38480 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
38490 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
384a0 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
384b0 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
384c0 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
384d0 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
384e0 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
384f0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
38500 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
38510 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
38520 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
38530 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
38540 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
38550 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
38560 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
38570 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
38580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
38590 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
385a0 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
385b0 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
385c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
385d0 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
385e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
385f0 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
38600 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
38610 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
38620 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
38630 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
38640 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
38650 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
38660 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
38670 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
38680 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
38690 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
386a0 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
386b0 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
386c0 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
386d0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
386e0 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
386f0 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
38700 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
38710 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
38720 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
38730 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
38740 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
38750 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
38760 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
38770 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
38780 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
38790 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
387a0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
387b0 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
387c0 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
387d0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
387e0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
387f0 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
38800 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
38810 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function