/ Hex Artifact Content
Login

Artifact 4b76d74d69af48c534c58fb723137dc6944bdedc:


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 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
55f0: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5600: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5610: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5620: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5630: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5640: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5650: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5660: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
5670: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5680: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56b0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
56c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
56d0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
56f0: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5700: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5710: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5720: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5730: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5740: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5750: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5770: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
5780: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5790: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57b0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
57c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
57d0: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
57f0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5810: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5830: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5840: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5850: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5860: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5870: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
5880: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5890: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
58c0: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
58d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
58e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58f0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5900: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5910: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5920: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5930: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5940: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5950: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5960: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5970: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5980: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5990: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59a0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59c0: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
59d0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
59e0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a10: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a20: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a50: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5a60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a70: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a90: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5aa0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ab0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ad0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5ae0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5af0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b10: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b20: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5b60: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b80: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ba0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bc0: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5be0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c00: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c30: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5c60: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5c80: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5c90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ca0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5cc0: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5cd0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5ce0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5cf0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d00: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d10: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d20: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d30: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d50: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5d60: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5d70: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5d80: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5d90: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5da0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5db0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5dc0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5dd0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5de0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5df0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e10: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e20: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5e60: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5e70: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5e80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5eb0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5ec0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5ed0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5ef0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f00: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f30: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f40: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5f70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f80: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5f90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fa0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5fc0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5fd0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5fe0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ff0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6000: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6010: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6020: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6030: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
6090: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60a0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
60d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
60e0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6150: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6160: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
6190: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61a0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
61d0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
61e0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
61f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6200: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6220: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6230: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6240: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6250: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6260: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6270: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6280: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
6290: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
62c0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
62d0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
62e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6300: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6310: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6320: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6330: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6340: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6360: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6370: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6380: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6390: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
63a0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
63b0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
63c0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
63d0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
63e0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
63f0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6400: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6410: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6420: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6430: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6440: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6450: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6460: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6470: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6480: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6490: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
64a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
64b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
64c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
64d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
64e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
64f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
65a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
65b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
65c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
65d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
65e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
65f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
66a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
66b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
66c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
66d0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
66e0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
66f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6700: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6710: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6720: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6730: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6740: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6750: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6760: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6770: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6780: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6790: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
67a0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
67b0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
67c0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
67d0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
67e0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
67f0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6800: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6810: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6820: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6830: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6840: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6850: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
6860: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6870: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6880: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6890: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
68a0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
68b0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
68c0: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
68d0: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
68e0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
68f0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6910: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6920: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6930: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6940: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6950: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6960: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6970: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6980: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6990: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
69a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
69c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69d0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
69e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
69f0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a00: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a20: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6a30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a40: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6a50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a60: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6a70: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6a90: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6aa0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ab0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6ac0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6ad0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6ae0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6af0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b00: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6b10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6b20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b30: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b40: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6b50: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6b60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6b70: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6b80: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ba0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bb0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6bc0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6bd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6be0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6bf0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6c10: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6c20: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6c30: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6c40: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6c50: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6c60: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6c70: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6c80: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6c90: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6ca0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6cb0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6cc0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6cd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6ce0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6cf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d00: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6d10: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6d20: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6d30: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6d40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6d50: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6d60: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6d70: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6d80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6d90: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6da0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6db0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6dc0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6dd0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6de0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6df0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e00: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6e10: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6e20: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6e30: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6e40: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6e50: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6e60: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6e70: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6e80: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6e90: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ea0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6eb0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6ec0: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6ed0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6ee0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6ef0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f00: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6f10: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6f20: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6f30: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6f40: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6f50: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6f60: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6f70: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6f80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6f90: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6fa0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6fb0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
6fc0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
6fd0: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
6fe0: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
6ff0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7000: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7010: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7020: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7030: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7040: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7050: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
7060: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
7070: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7080: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7090: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
70a0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
70b0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
70c0: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
70d0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
70e0: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
70f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7100: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7110: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7120: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7130: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7140: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7150: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
7160: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
7170: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7180: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7190: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
71a0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
71b0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
71c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
71d0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
71e0: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
71f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7200: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7210: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7220: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7230: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7240: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7250: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
7260: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
7270: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7280: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7290: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
72a0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
72c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
72d0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
72e0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
72f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7300: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7310: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7320: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7330: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7340: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7350: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7360: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
7370: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7380: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7390: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
73a0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
73b0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
73c0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
73d0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
73e0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
73f0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7400: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7410: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7420: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7430: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7440: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7450: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
7460: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7470: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7480: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7490: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
74a0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
74b0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
74c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
74d0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
74e0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
74f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7500: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7510: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7520: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7530: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7540: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7550: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7560: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7570: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7580: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7590: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
75a0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
75b0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
75c0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
75d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
75e0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
75f0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7600: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7620: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7630: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7640: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7650: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
7660: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7670: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7680: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7690: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
76a0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
76b0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
76c0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
76d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
76e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
76f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7700: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7710: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7720: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7730: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7740: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7750: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
7760: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7770: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7780: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7790: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77a0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
77b0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
77c0: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
77d0: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
77e0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
77f0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7800: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7810: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7820: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7830: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7840: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7850: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
7860: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7870: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7880: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7890: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
78a0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
78b0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
78c0: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
78d0: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
78e0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
78f0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7900: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7910: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7920: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7930: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7940: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7950: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7960: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7970: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7980: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7990: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
79a0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
79b0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
79c0: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
79d0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
79e0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
79f0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a00: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7a10: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a20: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7a30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a40: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7a50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a60: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7a70: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a80: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7a90: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7aa0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7ab0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7ac0: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7ad0: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7ae0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7af0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b00: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7b10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7b20: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7b30: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7b40: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7b50: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7b60: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7b70: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7b80: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7b90: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7ba0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7bb0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7bc0: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7bd0: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7be0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7bf0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c00: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7c10: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7c20: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7c30: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7c40: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7c50: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7c60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7c70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7c80: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7c90: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7ca0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7cb0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7cc0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7cd0: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7ce0: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7cf0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d00: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7d10: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7d20: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7d30: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7d40: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7d50: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7d60: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7d70: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7d80: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7d90: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7da0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7db0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7dc0: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7dd0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7de0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7df0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e00: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7e10: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7e20: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7e30: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7e40: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7e50: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7e60: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7e70: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7e80: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7e90: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ea0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7eb0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7ec0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7ed0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7ee0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7ef0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f00: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7f10: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7f20: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7f30: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7f40: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7f50: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7f60: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7f70: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7f80: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7f90: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7fa0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7fb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
7fc0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
7fd0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7fe0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7ff0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8000: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8010: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8020: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8030: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8040: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8050: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
8060: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8070: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8080: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8090: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
80a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
80b0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
80c0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
80d0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
80e0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
80f0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8100: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8110: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8120: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8130: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8140: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8150: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
8160: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8170: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8190: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
81c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81d0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
81e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81f0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8200: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8210: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8220: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8230: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8240: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8250: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
8260: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8270: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8280: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8290: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
82a0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
82b0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
82c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
82d0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
82e0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
82f0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8300: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8310: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8320: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8330: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8340: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8350: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8360: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8380: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8390: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
83a0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
83b0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
83c0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
83d0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
83e0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
83f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8400: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8410: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8420: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8430: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8440: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8450: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8460: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8470: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8480: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8490: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
84a0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
84b0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
84c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
84d0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
84e0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
84f0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8500: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8510: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8520: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8530: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8540: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8550: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8560: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8570: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8580: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8590: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
85a0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
85b0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
85c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
85d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
85e0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
85f0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8600: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8610: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8620: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8630: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8640: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8650: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8660: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8670: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8680: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8690: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
86a0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
86b0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
86c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
86d0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
86e0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
86f0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8700: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8710: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8720: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8730: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8740: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8750: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8760: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8770: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8780: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
87a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
87c0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
87d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
87e0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
87f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8800: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8810: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8820: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8830: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8840: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8850: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8860: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8870: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8880: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8890: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88a0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
88b0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
88c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
88d0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
88e0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
88f0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8900: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8920: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8930: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8940: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8950: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8960: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8970: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8980: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8990: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
89a0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
89b0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
89c0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
89d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
89e0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
89f0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a00: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8a10: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8a20: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8a30: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8a40: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8a50: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a60: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8a70: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8a80: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8a90: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8aa0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8ab0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8ac0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8ad0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8ae0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8af0: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b00: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8b10: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8b20: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8b30: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8b40: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8b50: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8b60: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8b70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8b80: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8b90: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8ba0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8bb0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8bc0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8bd0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8be0: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8bf0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c00: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8c10: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8c20: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8c30: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8c40: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8c50: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8c60: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8c70: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8c80: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8c90: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8cb0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8cc0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8cd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8ce0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8cf0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d00: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8d10: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8d20: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8d30: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8d40: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8d50: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8d60: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8d70: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8d80: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8d90: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8da0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8db0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8dc0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8dd0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8de0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8df0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e00: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8e10: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8e20: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8e30: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e40: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e50: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8e60: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8e70: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8e80: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8e90: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ea0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8eb0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8ec0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8ed0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8ee0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8ef0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f00: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8f10: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8f20: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8f30: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f40: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f50: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8f60: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8f70: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8f80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8f90: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8fa0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8fb0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8fc0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8fd0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8fe0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ff0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9000: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9010: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9020: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9030: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9040: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9050: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9060: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
9070: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
9080: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
9090: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
90a0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
90b0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
90c0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
90d0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
90e0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
90f0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9100: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9110: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9120: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9130: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9140: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9150: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9170: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9190: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
91a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
91b0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
91c0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
91d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
91e0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
91f0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9200: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9210: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9220: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9230: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9240: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9250: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9260: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9270: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9280: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9290: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
92a0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
92b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
92c0: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
92d0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
92e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
92f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9300: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9310: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9320: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9330: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9340: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9350: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9360: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9370: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9380: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9390: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
93a0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
93b0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
93c0: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
93d0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
93e0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
93f0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9400: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9410: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9420: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9430: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9440: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9450: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9460: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9470: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9480: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9490: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
94a0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
94b0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
94c0: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
94d0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
94e0: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
94f0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9500: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9510: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9520: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9530: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9540: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9550: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9560: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9570: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9580: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9590: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
95a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
95b0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
95c0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
95d0: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
95e0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
95f0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9600: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9610: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9620: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9630: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9640: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9650: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9660: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9670: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9680: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9690: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
96a0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
96b0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
96c0: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
96d0: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
96e0: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
96f0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9700: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9710: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9720: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9730: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9740: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9750: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9760: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9770: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9780: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9790: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
97a0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
97b0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
97c0: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
97d0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
97e0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
97f0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9800: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9810: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9820: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9840: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9850: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9860: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9870: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9880: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9890: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
98a0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
98b0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
98c0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
98d0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
98e0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
98f0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9900: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9910: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9920: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9930: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9940: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9950: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9960: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9970: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9980: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9990: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
99a0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
99b0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
99c0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
99d0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
99e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
99f0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9a00: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9a10: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9a20: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9a30: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a40: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a50: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9a60: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9a70: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9a80: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9a90: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9aa0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9ab0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9ac0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9ad0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9ae0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9af0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9b00: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9b10: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9b20: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9b30: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b40: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b50: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9b60: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9b70: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9b80: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9b90: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9ba0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9bb0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9bc0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9bd0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9be0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9bf0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9c00: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9c10: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9c20: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9c30: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c40: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c50: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9c60: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9c70: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9c80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9c90: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9ca0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9cb0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9cc0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9cd0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9ce0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9cf0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9d00: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9d10: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9d20: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9d30: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d40: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d50: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9d60: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9d70: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9d80: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9d90: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9da0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9db0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9dc0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9dd0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9de0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9df0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9e00: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9e10: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9e20: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9e30: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e40: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e50: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9e60: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9e70: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9e80: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9e90: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ea0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9eb0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9ec0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9ed0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9ee0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9ef0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9f00: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9f10: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9f20: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9f30: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f50: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9f60: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9f70: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9f80: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9f90: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9fa0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9fb0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9fc0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9fd0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9fe0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ff0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a000: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a010: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a020: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a030: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a040: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a050: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a060: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a070: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a080: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a090: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a0a0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a0b0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a0c0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a0d0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a0e0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a0f0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a100: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a110: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a120: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a130: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a140: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a150: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a160: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a170: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a180: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a190: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a1a0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a1b0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a1c0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a1d0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a1e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a1f0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a200: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a210: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a220: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a230: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a240: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a250: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a260: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a270: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a280: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a290: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a2a0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a2b0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a2c0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a2d0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a2e0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a2f0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a300: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a310: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a320: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a330: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a340: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a350: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a360: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a370: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a380: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a390: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a3a0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a3b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a3c0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a3d0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a3e0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a3f0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a400: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a410: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a420: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a430: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a440: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a450: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a460: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a470: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a480: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a490: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a4a0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a4b0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a4c0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a4d0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a4e0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a4f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a500: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a510: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a520: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a530: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a540: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a550: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a560: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a570: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a580: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a590: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a5a0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a5b0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a5c0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a5d0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a5e0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a5f0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a600: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a610: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a620: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a630: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a640: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a650: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a660: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a670: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a680: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a690: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a6a0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a6b0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a6c0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a6d0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a6e0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a6f0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a700: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a710: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a720: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a730: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a740: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a750: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a760: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a770: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a780: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a790: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a7a0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a7b0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a7c0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a7d0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a7e0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a7f0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a800: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a820: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a830: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a840: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a850: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a860: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a870: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a880: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a890: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a8a0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a8b0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a8c0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a8d0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a8e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a8f0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a900: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a910: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a920: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a930: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a940: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a950: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a960: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a970: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a980: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a990: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a9a0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a9b0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a9c0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a9d0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a9e0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a9f0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
aa00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
aa10: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
aa20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
aa30: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
aa40: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
aa50: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
aa60: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
aa70: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
aa80: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
aa90: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
aaa0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
aab0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
aac0: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
aad0: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
aae0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
aaf0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
ab00: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
ab10: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
ab20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab30: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab40: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab50: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
ab60: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ab70: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
ab80: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
ab90: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
aba0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
abb0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
abc0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
abd0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
abe0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
abf0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
ac00: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
ac10: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
ac20: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac40: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac50: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
ac60: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
ac70: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
ac80: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
ac90: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
aca0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
acb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
acc0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
acd0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
ace0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
acf0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
ad00: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
ad10: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ad20: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
ad30: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad40: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad50: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ad60: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ad70: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ad80: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ad90: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ada0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
adb0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
adc0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
add0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ade0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
adf0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ae00: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
ae10: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ae20: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ae30: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae40: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae50: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
ae60: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
ae70: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
ae80: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
ae90: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
aea0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
aeb0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
aec0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
aed0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
aee0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aef0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
af00: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
af10: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
af20: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
af30: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af40: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af50: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
af60: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
af70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
af80: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
af90: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
afa0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
afb0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
afc0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
afd0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
afe0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
aff0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b000: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b010: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b020: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b030: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b040: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b050: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b060: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b070: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b080: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b090: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b0a0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b0b0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b0c0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b0d0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b0e0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b0f0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b100: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b110: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b120: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b130: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b140: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b150: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b160: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b170: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b180: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b190: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b1a0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b1b0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b1c0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b1d0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b1e0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b1f0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b200: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b210: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b220: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b230: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b240: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b250: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b260: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b270: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b280: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b290: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b2a0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b2b0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b2c0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b2d0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b2e0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b2f0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b300: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b310: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b320: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b330: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b340: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b350: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b360: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b370: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b380: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b390: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b3a0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b3b0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b3c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b3d0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b3e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b3f0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b400: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b410: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b420: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b430: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b440: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b450: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b460: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b470: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b480: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b490: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b4a0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b4b0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b4c0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b4d0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b4e0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b4f0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b500: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b510: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b520: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b530: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b540: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b550: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b560: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b570: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b580: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b590: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b5a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b5b0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b5c0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b5d0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b5e0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b5f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b600: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b610: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b620: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b630: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b640: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b650: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b660: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b670: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b680: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b690: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b6a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b6b0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b6c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b6d0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b6e0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b6f0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
b700: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
b710: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
b720: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
b730: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
b740: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
b750: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
b760: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
b770: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
b780: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
b790: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b7a0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
b7b0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
b7c0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
b7d0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
b7e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b7f0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
b800: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
b810: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
b820: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
b830: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
b840: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
b850: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
b860: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
b870: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
b880: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
b890: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
b8a0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
b8b0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
b8c0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
b8d0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
b8e0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
b8f0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
b900: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
b910: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
b920: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
b930: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
b940: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
b950: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
b960: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b970: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
b980: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b990: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
b9a0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
b9b0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
b9c0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
b9d0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
b9e0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
b9f0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
ba00: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
ba10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
ba20: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
ba30: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
ba40: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
ba50: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
ba60: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
ba70: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
ba80: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
ba90: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
baa0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bab0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
bac0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
bad0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
bae0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
baf0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
bb00: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
bb10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
bb20: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
bb30: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
bb40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
bb50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bb60: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
bb70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
bb80: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
bb90: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bba0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
bbb0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
bbc0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bbd0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bbe0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bbf0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bc00: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
bc10: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bc20: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bc30: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bc40: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bc60: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bc70: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bc90: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bca0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bcb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bcc0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bcd0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bcf0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
bd00: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
bd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd20: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
bd30: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
bd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd50: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
bd60: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
bd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bd80: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
bd90: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
bda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
bdb0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
bdc0: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
bdd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
bde0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
bdf0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
be00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
be10: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
be20: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
be30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
be40: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
be50: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
be60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
be80: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
be90: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
bea0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
beb0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
bec0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
bed0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
bee0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
bef0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
bf00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
bf10: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bf20: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
bf30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
bf40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf50: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
bf60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
bf70: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
bf80: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bf90: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
bfa0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
bfc0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
bfd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
bfe0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bff0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c000: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c010: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c020: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c030: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c040: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c050: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c060: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c070: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c080: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c090: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c0a0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c0b0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c0c0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c0d0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c0e0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c0f0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c100: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c110: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c120: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c130: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c140: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c150: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c160: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c170: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c180: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c190: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c1a0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c1b0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c1c0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c1d0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c1e0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c1f0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
c200: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
c210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c220: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c230: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c240: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
c250: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
c260: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
c270: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
c280: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
c290: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
c2a0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
c2b0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
c2c0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
c2d0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
c2e0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
c2f0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
c300: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
c310: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
c320: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
c330: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
c340: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
c350: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
c360: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
c370: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
c380: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
c390: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
c3a0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
c3b0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
c3c0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
c3d0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
c3e0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
c3f0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c400: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
c410: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
c420: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
c430: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
c440: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
c450: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c460: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
c470: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
c480: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
c490: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c4a0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
c4b0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
c4c0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
c4d0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
c4e0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
c4f0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
c500: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
c510: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
c520: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
c530: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
c540: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
c550: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
c560: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
c570: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
c580: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
c590: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
c5a0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
c5b0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
c5c0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
c5d0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
c5e0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
c5f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c600: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
c610: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
c620: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
c630: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c640: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
c650: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
c660: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
c670: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c680: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
c690: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
c6a0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
c6b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c6c0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
c6d0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
c6e0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
c6f0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
c700: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
c710: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
c720: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
c730: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
c740: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c750: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c760: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
c770: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
c780: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
c790: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
c7a0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
c7b0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
c7c0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
c7d0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
c7e0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
c7f0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
c800: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
c810: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
c820: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
c830: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
c840: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
c850: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
c860: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c870: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
c880: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
c890: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
c8a0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
c8b0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
c8c0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
c8d0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
c8e0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
c8f0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
c900: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c910: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
c920: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
c930: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
c940: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
c950: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
c960: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
c970: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
c980: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
c990: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
c9a0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
c9b0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
c9c0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
c9d0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
c9e0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
c9f0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
ca00: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
ca10: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
ca20: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
ca30: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
ca40: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
ca50: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
ca60: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
ca70: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
ca80: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
ca90: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
caa0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
cab0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
cac0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
cad0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
cae0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
caf0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
cb00: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
cb10: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
cb20: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
cb30: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
cb40: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
cb50: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
cb60: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
cb70: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
cb80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cb90: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
cba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
cbb0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
cbc0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
cbd0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
cbe0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
cbf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
cc00: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
cc10: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
cc20: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
cc30: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
cc40: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
cc50: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
cc60: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
cc70: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
cc80: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
cc90: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
cca0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
ccb0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
ccc0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
ccd0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cce0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
ccf0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
cd00: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
cd10: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
cd20: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
cd30: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cd40: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
cd50: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
cd60: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
cd70: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
cd80: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
cd90: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
cda0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
cdb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cdc0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
cdd0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cde0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
cdf0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ce00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
ce10: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ce20: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ce30: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
ce40: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ce50: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
ce60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ce70: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
ce80: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ce90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
cea0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
ceb0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
cec0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
ced0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
cee0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
cef0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
cf00: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
cf10: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
cf20: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
cf30: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
cf40: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
cf50: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
cf60: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
cf70: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
cf80: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
cf90: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
cfa0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
cfb0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
cfc0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
cfd0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
cfe0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
cff0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d010: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d020: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d030: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d040: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d050: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d060: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d070: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d080: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d090: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d0a0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d0b0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d0c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d0d0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d0e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d0f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d100: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d110: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d120: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d130: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d140: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d150: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d160: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d170: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d180: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d190: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d1a0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d1b0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d1c0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d1d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d1e0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d1f0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
d200: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
d210: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
d220: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
d230: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
d240: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
d250: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d260: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
d270: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
d280: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
d290: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
d2a0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
d2b0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
d2c0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
d2d0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
d2e0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
d2f0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
d300: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
d310: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
d320: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
d330: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
d340: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
d350: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d360: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
d370: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
d380: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
d390: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
d3a0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
d3b0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
d3c0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
d3d0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
d3e0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d3f0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
d400: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
d410: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
d420: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
d430: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
d440: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
d450: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
d460: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
d470: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
d480: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
d490: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
d4a0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
d4b0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
d4c0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
d4d0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
d4e0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
d4f0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
d500: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
d510: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
d520: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d530: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
d540: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d550: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
d560: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
d570: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d580: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
d590: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
d5a0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
d5b0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
d5c0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
d5d0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
d5e0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
d5f0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
d600: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
d610: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
d620: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
d630: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
d640: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
d650: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
d660: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
d670: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
d680: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
d690: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
d6a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d6b0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
d6c0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
d6d0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
d6e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d6f0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
d700: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d710: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
d720: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
d730: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d740: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
d750: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d760: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
d770: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
d780: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
d790: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
d7a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
d7b0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
d7c0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
d7d0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
d7e0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
d7f0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
d800: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
d810: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
d820: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
d830: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
d840: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
d850: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
d860: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d870: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
d880: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
d890: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
d8a0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
d8b0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
d8c0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
d8d0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
d8e0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
d8f0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
d900: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
d910: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
d920: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
d930: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
d940: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
d950: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d960: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
d970: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
d980: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
d990: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
d9a0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
d9b0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
d9c0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
d9d0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
d9e0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
d9f0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
da00: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
da10: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
da20: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
da30: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
da40: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
da50: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
da60: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
da70: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
da80: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
da90: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
daa0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
dab0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
dac0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
dad0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
dae0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
daf0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
db00: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
db10: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
db20: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
db30: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
db40: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
db50: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
db60: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
db70: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
db80: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
db90: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
dba0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
dbb0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dbc0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
dbd0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
dbe0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
dbf0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
dc00: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
dc10: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
dc20: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
dc30: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
dc40: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
dc50: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
dc60: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dc70: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
dc80: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
dc90: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
dca0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
dcb0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
dcc0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
dcd0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
dce0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
dcf0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
dd00: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
dd10: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
dd20: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
dd30: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
dd40: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
dd50: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
dd60: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
dd70: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
dd80: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
dd90: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
dda0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
ddb0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
ddc0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
ddd0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
dde0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
ddf0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
de00: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
de10: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
de20: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
de30: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
de40: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
de50: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
de60: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
de70: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
de80: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
de90: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
dea0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
deb0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
dec0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
ded0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
dee0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
def0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
df00: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
df10: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
df20: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
df30: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
df40: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
df50: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
df60: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
df70: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
df80: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
df90: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
dfa0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
dfb0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
dfc0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
dfd0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
dfe0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
dff0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e000: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e010: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e020: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e030: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e040: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e050: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e060: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e070: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e080: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e090: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e0a0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e0b0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e0c0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e0d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e0e0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e0f0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e100: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e110: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e120: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e130: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e140: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e150: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e160: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e170: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e180: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e190: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e1a0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e1b0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e1c0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e1d0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e1e0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e1f0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
e200: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
e210: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e220: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
e230: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
e240: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
e250: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
e260: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
e270: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
e280: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e290: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e2a0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
e2b0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
e2c0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
e2d0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
e2e0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
e2f0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e300: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
e310: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
e320: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
e330: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e340: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
e350: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
e360: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
e370: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
e380: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e390: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
e3a0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e3b0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
e3c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e3d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
e3e0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
e3f0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
e400: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e410: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
e420: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
e430: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
e440: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
e450: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
e460: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
e470: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
e480: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
e490: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
e4a0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
e4b0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
e4c0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
e4d0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
e4e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
e4f0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
e500: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e510: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e520: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
e530: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
e540: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e550: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
e560: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e570: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e580: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
e590: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e5a0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
e5b0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
e5c0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
e5d0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
e5e0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
e5f0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e600: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
e610: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
e620: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
e630: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e640: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e650: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
e660: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e670: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
e680: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
e690: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
e6a0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
e6b0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
e6c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e6d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e6e0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
e6f0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
e700: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
e710: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
e720: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e730: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e740: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
e750: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
e760: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e770: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e780: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
e790: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e7a0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e7b0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
e7c0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e7d0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
e7e0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
e7f0: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
e800: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
e810: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
e820: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
e830: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
e840: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
e850: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e860: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e870: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
e880: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
e890: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
e8a0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
e8b0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
e8c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
e8d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e8e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
e8f0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
e900: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
e910: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
e920: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
e930: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
e940: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
e950: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e960: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
e970: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
e980: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
e990: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
e9a0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
e9b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e9c0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
e9d0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
e9e0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
e9f0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
ea00: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
ea10: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
ea20: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
ea30: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ea40: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ea50: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
ea60: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
ea70: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
ea80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ea90: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
eaa0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
eab0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
eac0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
ead0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
eae0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
eaf0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
eb00: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
eb10: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
eb20: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
eb30: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
eb40: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
eb50: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
eb60: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
eb70: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
eb80: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
eb90: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
eba0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
ebb0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
ebc0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
ebd0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
ebe0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
ebf0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ec00: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
ec10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ec20: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
ec30: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
ec40: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ec50: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
ec60: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ec70: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
ec80: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
ec90: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
eca0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
ecb0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ecc0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ecd0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
ece0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
ecf0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
ed00: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
ed10: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ed20: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
ed30: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ed40: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
ed50: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
ed60: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
ed70: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
ed80: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
ed90: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
eda0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
edb0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
edc0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
edd0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
ede0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
edf0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
ee00: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ee10: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ee20: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
ee30: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ee40: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ee50: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
ee60: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
ee70: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
ee80: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
ee90: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
eea0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
eeb0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
eec0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
eed0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
eee0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
eef0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ef00: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
ef10: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ef20: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
ef30: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
ef40: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ef50: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
ef60: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
ef70: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
ef80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ef90: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
efa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
efb0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
efc0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
efd0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
efe0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
eff0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f000: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f010: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f020: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f030: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f040: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f060: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f070: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f080: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f090: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f0a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f0b0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f0c0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f0d0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f0e0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f0f0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f100: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f110: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f120: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f130: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f140: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f150: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f160: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f170: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f180: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f190: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f1a0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f1b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f1c0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f1d0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f1e0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f1f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
f200: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f210: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
f220: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
f230: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
f240: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
f250: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
f260: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
f270: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
f280: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
f290: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
f2a0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
f2b0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
f2c0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
f2d0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f2e0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f300: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f310: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
f320: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
f330: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f340: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f350: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
f360: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
f370: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
f380: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
f390: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
f3a0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
f3b0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
f3c0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
f3d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
f3e0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
f3f0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
f400: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f410: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
f420: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
f430: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
f440: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f450: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
f460: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f470: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
f480: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
f490: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f4a0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
f4b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f4c0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
f4d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f4e0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
f4f0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
f500: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f510: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
f520: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
f530: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
f540: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
f550: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f560: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
f570: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f580: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
f590: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
f5a0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
f5b0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
f5c0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
f5d0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
f5e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
f5f0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
f600: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
f610: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
f620: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
f630: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f640: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
f650: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
f660: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
f670: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
f680: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
f690: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
f6a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f6b0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
f6c0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
f6d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f6e0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
f6f0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f700: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
f710: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
f720: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
f730: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
f740: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
f750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f760: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
f770: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f780: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
f790: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
f7a0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
f7b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
f7c0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
f7d0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
f7e0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
f7f0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
f800: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
f810: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
f820: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
f830: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
f840: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
f850: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
f860: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f870: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f880: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
f890: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
f8a0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
f8b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
f8c0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
f8d0: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
f8e0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
f8f0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f900: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f910: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
f920: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
f930: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
f940: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f950: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
f960: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
f970: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
f980: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
f990: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
f9a0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
f9b0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
f9c0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
f9d0: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
f9e0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
f9f0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
fa00: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
fa10: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
fa20: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
fa30: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
fa40: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
fa50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa60: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
fa70: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
fa80: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
fa90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
faa0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
fab0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
fac0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
fad0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
fae0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
faf0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
fb00: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
fb10: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
fb20: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
fb30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fb40: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
fb50: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
fb60: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fb70: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
fb80: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
fb90: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
fba0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
fbb0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
fbc0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
fbd0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
fbe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
fbf0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
fc00: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
fc10: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
fc20: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
fc30: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fc40: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
fc50: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fc60: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
fc70: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
fc80: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
fc90: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fca0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
fcb0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
fcc0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fcd0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
fce0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
fcf0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
fd00: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
fd10: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
fd20: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
fd30: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
fd40: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
fd50: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
fd60: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
fd70: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
fd80: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
fd90: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
fda0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
fdb0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
fdc0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
fdd0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
fde0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
fdf0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
fe00: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
fe10: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
fe20: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
fe30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fe40: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
fe50: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
fe60: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
fe70: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
fe80: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fe90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fea0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
feb0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
fec0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
fed0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
fee0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
fef0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
ff00: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
ff10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ff20: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
ff30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ff40: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
ff50: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ff60: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
ff70: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
ff80: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ff90: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
ffa0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
ffb0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
ffc0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
ffd0: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
ffe0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
fff0: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10000 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10010 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10020 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10030 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10040 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10050 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
10060 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
10070 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
10080 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
10090 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
100a0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
100b0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
100c0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
100d0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
100e0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
100f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10100 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10110 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10120 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10130 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10140 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10150 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10160 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
10170 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
10180 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
10190 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
101a0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
101b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
101c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
101d0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
101e0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
101f0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10200 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10210 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10220 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10230 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10240 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10250 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
10260 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10270 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
10280 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
10290 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
102a0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
102b0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
102c0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
102d0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
102e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
102f0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10300 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10310 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10320 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10330 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10340 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10350 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
10360 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10370 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
10380 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
10390 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
103a0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
103b0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
103c0 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
103d0 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
103e0 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
103f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10400 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
10410 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10420 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10430 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
10440 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
10450 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
10460 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
10470 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
10480 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
10490 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
104a0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
104b0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
104c0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
104d0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
104e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
104f0 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
10500 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10510 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
10520 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
10530 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
10540 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
10550 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
10560 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
10570 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
10580 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
10590 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
105a0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
105b0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
105c0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
105d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
105e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
105f0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
10600 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10610 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
10620 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
10630 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
10640 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
10650 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
10660 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
10670 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10680 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
10690 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
106a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
106b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
106c0 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
106d0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
106e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
106f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10700 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
10710 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
10720 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
10730 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
10740 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
10750 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
10760 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
10770 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
10780 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
10790 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
107a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
107b0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
107c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
107d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
107e0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
107f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10800 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10810 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
10820 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
10830 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
10840 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
10850 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
10860 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
10870 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10880 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
10890 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
108a0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
108b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
108c0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
108d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
108e0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
108f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10900 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
10910 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
10920 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
10930 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10940 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
10950 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
10960 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
10970 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
10980 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
10990 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
109a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
109b0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
109c0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
109d0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
109e0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
109f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10a00 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
10a10 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
10a20 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
10a30 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
10a40 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
10a50 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
10a60 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10a70 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10a80 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10a90 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10aa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10ab0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10ac0 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
10ad0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10ae0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
10af0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
10b00 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
10b10 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
10b20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10b30 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
10b40 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
10b50 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
10b60 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10b70 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10b80 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10b90 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10ba0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10bb0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10bc0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10bd0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
10be0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10bf0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
10c00 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
10c10 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
10c20 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
10c30 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
10c40 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10c50 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
10c60 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10c70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10c80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10c90 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10ca0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10cb0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10cc0 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
10cd0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
10ce0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10cf0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
10d00 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
10d10 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
10d20 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
10d30 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
10d40 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
10d50 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
10d60 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10d70 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10d80 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10d90 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10da0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10db0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10dc0 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
10dd0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
10de0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
10df0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
10e00 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10e10 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
10e20 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
10e30 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
10e40 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
10e50 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
10e60 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10e70 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10e80 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10e90 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10ea0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10eb0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10ec0 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
10ed0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
10ee0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
10ef0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
10f00 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
10f10 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
10f20 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
10f30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
10f40 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
10f50 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
10f60 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10f70 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10f80 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10f90 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10fa0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10fb0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
10fc0 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
10fd0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
10fe0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
10ff0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11000 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11010 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11020 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11030 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11040 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11050 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11060 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
11070 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
11080 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
11090 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
110a0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
110b0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
110c0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
110d0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
110e0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
110f0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11100 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11110 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11120 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11130 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11140 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11150 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
11160 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
11170 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
11180 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
11190 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
111a0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
111b0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
111c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
111d0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
111e0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
111f0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11200 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11210 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11220 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11230 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11240 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11250 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
11260 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
11270 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
11280 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
11290 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
112a0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
112b0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
112c0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
112d0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
112e0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
112f0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11300 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11310 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11320 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11330 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11340 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11350 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
11360 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
11370 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
11380 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
11390 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
113a0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
113b0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
113c0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
113d0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
113e0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
113f0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11400 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11410 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11420 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11430 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11440 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11450 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
11460 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
11470 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11480 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
11490 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
114a0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
114b0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
114c0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
114d0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
114e0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
114f0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11500 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11510 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11520 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11530 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11540 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11550 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
11560 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
11570 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
11580 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
11590 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
115a0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
115b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
115c0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
115d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
115e0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
115f0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11600 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11610 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11620 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11630 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11640 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11660 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11670 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11680 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11690 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
116a0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
116b0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
116c0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
116d0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
116e0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
116f0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11700 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11710 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11720 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11730 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11740 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11750 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11760 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11770 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11780 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11790 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
117a0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
117b0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
117c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
117d0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
117e0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
117f0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
11800 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
11810 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
11820 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
11830 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
11840 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
11850 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
11860 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
11870 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
11880 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
11890 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
118a0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
118b0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
118c0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
118d0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
118e0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
118f0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
11900 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
11910 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
11920 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11930 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
11940 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
11950 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
11960 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11970 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11980 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
11990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
119a0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
119b0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
119c0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
119d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
119e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
119f0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
11a00 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
11a10 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
11a20 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
11a30 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
11a40 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
11a50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
11a60 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11a70 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11a80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11a90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11aa0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11ab0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11ac0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11ad0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11ae0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11af0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11b00 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
11b10 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
11b20 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
11b30 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
11b40 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
11b50 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
11b60 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11b70 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11b80 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11b90 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11ba0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11bb0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11bc0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11bd0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11be0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11bf0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11c00 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
11c10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
11c20 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11c30 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
11c40 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11c50 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
11c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11c70 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11c80 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11c90 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11ca0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11cb0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11cc0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11cd0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11ce0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11cf0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11d00 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
11d10 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
11d20 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11d30 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
11d40 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
11d50 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
11d60 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11d70 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11d80 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11d90 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11da0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11db0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11dc0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11dd0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11de0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11df0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11e00 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
11e10 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
11e20 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11e30 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
11e40 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11e50 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
11e60 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11e70 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11e80 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11e90 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11ea0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11eb0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11ec0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11ed0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11ee0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11ef0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11f00 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11f10 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11f20 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11f30 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11f40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11f50 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
11f60 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11f70 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11f80 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11fa0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11fb0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11fc0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
11fd0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
11fe0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
11ff0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12000 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12010 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12030 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12040 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12050 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
12060 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
12070 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
12080 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
12090 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
120a0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
120b0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
120c0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
120d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
120e0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
120f0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12100 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12110 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12120 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12130 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12140 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12150 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12160 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12170 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12180 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
12190 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
121a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
121b0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
121c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
121d0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
121e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
121f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12200 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12210 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12220 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12230 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12240 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12250 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12260 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
12270 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
12280 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12290 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
122a0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
122b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
122c0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
122d0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
122e0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
122f0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12300 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12310 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12320 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12330 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12350 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
12360 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
12370 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
12380 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
12390 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
123a0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
123b0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
123c0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
123d0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
123e0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
123f0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12400 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12410 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12420 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12430 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12440 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12450 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
12460 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
12470 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
12480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12490 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
124a0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
124b0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
124c0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
124d0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
124e0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
124f0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12500 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12510 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12520 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12530 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12540 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12550 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
12560 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12570 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
12580 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12590 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
125a0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
125b0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
125c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
125d0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
125e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
125f0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12600 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12610 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12620 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12630 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12640 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12650 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12660 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
12670 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12680 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12690 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
126a0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
126b0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
126c0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
126d0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
126e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
126f0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12700 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12710 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12720 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12730 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12740 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12750 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12760 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12770 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12780 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12790 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
127a0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
127b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
127c0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
127d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
127e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
127f0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
12800 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12810 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12820 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
12830 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
12840 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12850 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12860 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
12870 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12880 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12890 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
128a0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
128b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
128c0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
128d0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
128e0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
128f0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
12900 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12910 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
12920 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12930 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12940 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
12950 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
12960 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
12970 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
12980 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
12990 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
129a0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
129b0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
129c0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
129d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
129e0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
129f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12a00 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
12a10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
12a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12a30 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
12a40 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12a50 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
12a60 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
12a70 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
12a80 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
12a90 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
12aa0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
12ab0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12ac0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
12ad0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
12ae0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12af0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
12b00 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
12b10 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
12b20 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
12b30 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
12b40 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
12b50 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
12b60 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
12b70 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
12b80 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
12b90 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
12ba0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
12bb0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
12bc0 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
12bd0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
12be0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
12bf0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12c00 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
12c10 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
12c20 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
12c30 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
12c40 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
12c50 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
12c60 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
12c70 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12c80 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12c90 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
12ca0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12cc0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
12cd0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12ce0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12cf0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12d00 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
12d10 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12d20 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12d30 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
12d40 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
12d50 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
12d60 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12d70 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
12d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12d90 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
12da0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
12db0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
12dc0 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
12dd0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
12de0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
12df0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
12e00 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
12e10 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
12e20 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
12e30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12e40 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12e50 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
12e60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12e70 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
12e80 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
12e90 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
12ea0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
12eb0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12ec0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
12ed0 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
12ee0 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
12ef0 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
12f00 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
12f10 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
12f20 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
12f30 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
12f40 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
12f50 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
12f60 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
12f70 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
12f80 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
12f90 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12fa0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12fb0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12fc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12fd0 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
12fe0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12ff0 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13000 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13010 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13020 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13030 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13040 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13050 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
13060 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
13070 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
13080 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
13090 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
130a0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
130b0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
130c0 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
130d0 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
130e0 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
130f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13100 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13110 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13120 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13130 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13140 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13150 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13160 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
13170 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13180 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
13190 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
131a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
131b0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
131c0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
131d0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
131e0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
131f0 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
13200 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
13210 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
13220 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
13230 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
13240 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
13250 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
13260 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
13270 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13280 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
13290 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
132a0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
132b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
132c0 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20  FIG_PCACHE2].** 
132d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
132e0 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  tion..** ^There 
132f0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13300 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
13310 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
13320 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
13330 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
13340 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
13350 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
13360 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
13370 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
13380 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
13390 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
133a0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
133b0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
133c0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
133d0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
133e0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
133f0 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
13400 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
13410 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
13420 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
13430 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
13440 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
13450 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
13460 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
13470 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
13480 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13490 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a  _HDRSZ] option .
134a0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
134b0 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74  onfig()]..** ^It
134c0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
134d0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
134e0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
134f0 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13500 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13510 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13520 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
13530 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
13540 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
13550 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  yte aligned bloc
13560 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74  k of memory that
13570 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20  .** is at least 
13580 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
13590 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20  mory, otherwise 
135a0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
135b0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
135c0 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ned..** ^SQLite 
135d0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
135e0 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
135f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13600 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
13610 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
13620 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
13630 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
13640 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
13650 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
13660 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
13670 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
13680 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13690 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
136a0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
136b0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
136c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
136d0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
136e0 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
136f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13710 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
13720 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
13730 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13740 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13750 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13760 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13770 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
13780 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
13790 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
137a0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
137b0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
137c0 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
137d0 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
137e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
137f0 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
13800 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13810 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
13820 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13830 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
13840 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13850 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13860 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
13870 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
13880 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
13890 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
138a0 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
138b0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
138c0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
138d0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
138e0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
138f0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13900 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
13910 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
13920 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
13930 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
13940 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
13950 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
13960 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
13970 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13980 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
13990 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
139a0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
139b0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
139c0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
139d0 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
139e0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
139f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
13a00 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
13a10 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
13a20 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
13a30 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
13a40 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
13a50 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
13a60 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
13a70 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13a80 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
13a90 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13aa0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13ab0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13ac0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13ad0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13ae0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13af0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13b00 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
13b10 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
13b20 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
13b30 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
13b40 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
13b50 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
13b60 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13b70 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13b80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13b90 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
13ba0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13bb0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
13bc0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13bd0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
13be0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
13bf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13c10 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13c20 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
13c30 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13c40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13c50 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
13c60 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13c70 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
13c80 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13c90 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13ca0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13cb0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13cc0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
13cd0 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
13ce0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
13cf0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
13d00 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
13d10 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
13d20 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
13d30 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
13d40 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
13d50 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
13d60 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13d70 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13d80 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
13d90 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
13da0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
13db0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
13dc0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
13dd0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13de0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13df0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13e00 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13e10 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13e20 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
13e30 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
13e40 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
13e50 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
13e60 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
13e70 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
13e80 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
13e90 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
13ea0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
13eb0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13ec0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13ed0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13ee0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13ef0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13f00 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13f10 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
13f20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13f30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13f40 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
13f50 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13f60 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
13f70 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13f80 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13f90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13fa0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13fb0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
13fc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13fd0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
13fe0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
13ff0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14000 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14010 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14020 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14030 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14040 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14050 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
14060 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
14070 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
14080 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
14090 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
140a0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
140b0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
140c0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
140d0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
140e0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
140f0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14100 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14110 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14120 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14130 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14140 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14150 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
14160 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
14170 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
14180 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14190 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
141a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
141b0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
141c0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
141d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
141e0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
141f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14200 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
14210 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14220 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14230 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14250 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
14260 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
14270 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
14280 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
14290 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
142a0 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
142b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
142c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
142d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
142e0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
142f0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
14300 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
14310 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
14320 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
14330 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
14340 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14350 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
14360 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14370 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
14380 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
14390 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
143a0 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
143b0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
143c0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
143d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
143e0 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
143f0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
14400 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14410 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14420 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14430 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14440 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14450 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
14460 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14470 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14480 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14490 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
144a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
144b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
144c0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
144d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
144e0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
144f0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14500 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14510 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14520 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14530 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14540 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14550 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
14560 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
14570 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14580 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14590 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
145a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
145b0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
145c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
145d0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
145e0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
145f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14600 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
14610 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14620 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
14630 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14640 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14650 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14660 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
14670 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
14680 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
14690 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
146a0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
146b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
146c0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
146d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
146e0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
146f0 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14700 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14710 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
14720 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
14730 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
14740 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
14750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14760 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
14770 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
14780 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
14790 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
147a0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
147b0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
147c0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
147d0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
147e0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
147f0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
14800 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14810 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
14820 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
14830 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
14840 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
14850 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
14860 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
14870 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
14880 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14890 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
148a0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
148b0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
148c0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
148d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
148e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
148f0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14900 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
14910 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14920 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14930 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14940 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
14950 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
14960 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
14970 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14980 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
14990 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
149a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
149b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
149c0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
149d0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
149e0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
149f0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14a00 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
14a10 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
14a20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
14a30 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
14a40 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
14a50 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
14a60 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14a70 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14a80 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
14a90 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
14aa0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
14ab0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
14ac0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
14ad0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14ae0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
14af0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14b00 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
14b10 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
14b20 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
14b30 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
14b40 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
14b50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14b60 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14b70 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
14b80 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
14b90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14ba0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
14bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14bc0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
14bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14be0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14bf0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14c00 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
14c10 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
14c20 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
14c30 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
14c40 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
14c50 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
14c60 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
14c70 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
14c80 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
14c90 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14ca0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
14cb0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
14cc0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
14cd0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
14ce0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
14cf0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
14d00 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
14d10 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
14d20 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
14d30 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
14d40 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
14d50 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
14d60 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
14d70 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
14d80 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
14d90 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
14da0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
14db0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
14dc0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
14dd0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
14de0 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
14df0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
14e00 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
14e10 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
14e20 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
14e30 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
14e40 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
14e50 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
14e60 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14e70 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
14e80 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
14e90 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
14ea0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
14eb0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
14ec0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
14ed0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
14ee0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
14ef0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14f00 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
14f10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14f20 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14f30 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
14f40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14f50 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14f60 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
14f70 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
14f80 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
14f90 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
14fa0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
14fb0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
14fc0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
14fd0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
14fe0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
14ff0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
15000 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
15010 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
15020 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15030 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
15040 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
15050 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
15060 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
15070 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
15080 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
15090 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
150a0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
150b0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
150c0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
150d0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
150e0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
150f0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
15100 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
15110 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
15120 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
15130 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
15140 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
15150 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
15160 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
15170 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
15180 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
15190 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
151a0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
151b0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
151c0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
151d0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
151e0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
151f0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
15200 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
15210 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15220 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
15230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15240 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
15250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15260 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
15270 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15280 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
15290 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
152a0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
152b0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
152c0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
152d0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
152e0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
152f0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
15300 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
15310 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15320 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15330 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15340 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15350 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
15360 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15370 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
15380 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15390 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
153a0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
153b0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
153c0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
153d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
153e0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
153f0 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
15400 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
15410 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
15420 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15430 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15440 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15450 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
15460 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
15470 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
15480 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
15490 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
154a0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
154b0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
154c0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
154d0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
154e0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
154f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15500 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15520 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15530 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15540 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15550 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
15560 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
15570 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
15580 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
15590 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
155a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
155b0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
155c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
155d0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
155e0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
155f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
15600 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
15610 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
15620 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
15630 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15640 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
15650 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
15660 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
15670 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15680 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
15690 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
156a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
156b0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
156c0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
156d0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
156e0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
156f0 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
15700 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
15710 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
15720 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
15730 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
15740 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
15750 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15760 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15770 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
15780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15790 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
157a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
157b0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
157c0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
157d0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
157e0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
157f0 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15800 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15810 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15820 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15830 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
15840 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
15850 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15860 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
15870 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15880 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
15890 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
158a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
158b0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
158c0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
158d0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
158e0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
158f0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
15900 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
15910 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
15920 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15930 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
15940 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
15950 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
15960 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
15970 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
15980 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
15990 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
159a0 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
159b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
159c0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
159d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
159e0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
159f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
15a00 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
15a10 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
15a20 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
15a30 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
15a40 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
15a50 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15a60 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15a70 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
15a80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15a90 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
15aa0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
15ab0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15ac0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
15ad0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15ae0 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
15af0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
15b00 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
15b10 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
15b20 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
15b30 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
15b40 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
15b50 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15b60 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
15b70 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
15b80 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
15b90 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
15ba0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
15bb0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
15bc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15bd0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
15be0 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
15bf0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15c00 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
15c10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15c20 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
15c30 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15c40 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
15c50 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
15c60 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
15c70 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
15c80 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
15c90 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15ca0 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
15cb0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
15cc0 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
15cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15ce0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
15cf0 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
15d00 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
15d10 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
15d20 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
15d30 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
15d40 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
15d50 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
15d60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15d70 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
15d80 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15d90 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
15da0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15db0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
15dc0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
15dd0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
15de0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
15df0 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
15e00 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
15e10 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
15e20 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
15e30 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
15e40 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
15e50 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
15e60 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
15e70 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
15e80 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
15e90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
15ea0 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
15eb0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
15ec0 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
15ed0 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
15ee0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
15ef0 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
15f00 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
15f10 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
15f20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
15f30 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
15f40 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
15f50 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
15f60 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
15f70 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
15f80 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
15f90 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
15fa0 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
15fb0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
15fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15fd0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
15fe0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
15ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16000 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
16010 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
16020 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16030 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
16040 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
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 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
16070 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
16080 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
160a0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
160b0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
160c0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
160d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
160e0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
160f0 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
16100 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16110 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16130 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
16140 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16150 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16160 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16170 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
16180 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
16190 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
161a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
161b0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
161c0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
161d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
161e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
161f0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
16200 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16210 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16230 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
16240 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16250 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
16260 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
16270 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
16280 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
16290 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
162a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
162b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
162c0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
162d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
162e0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
162f0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
16300 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16310 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16320 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16330 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16340 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16350 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
16360 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
16370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16380 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
16390 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
163a0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
163b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
163c0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
163d0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
163e0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
163f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16400 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
16410 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
16420 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
16430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16440 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16450 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
16460 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
16470 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16480 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
16490 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
164a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
164b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
164c0 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
164d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
164e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
164f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16500 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16510 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
16520 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
16530 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16540 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
16550 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
16560 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
16570 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16580 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
16590 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
165a0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
165b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
165c0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
165d0 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
165e0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
165f0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
16600 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
16610 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
16620 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16630 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16640 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16650 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16660 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
16670 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16680 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
16690 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
166a0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
166b0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
166c0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
166d0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
166e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
166f0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
16700 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
16710 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
16720 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
16730 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
16740 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16750 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
16760 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
16770 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
16780 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16790 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
167a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
167b0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
167c0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
167d0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
167e0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
167f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
16800 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
16810 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
16820 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16830 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
16840 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16850 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
16860 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
16870 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
16880 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
16890 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
168a0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
168b0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
168c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
168d0 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
168e0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
168f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16900 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
16910 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
16920 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
16930 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
16940 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
16950 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
16960 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16970 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
16980 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16990 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
169a0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
169b0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
169c0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
169d0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
169e0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
169f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16a00 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
16a10 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
16a20 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
16a30 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16a40 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
16a50 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
16a60 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16a70 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
16a80 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
16a90 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
16aa0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
16ab0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
16ac0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
16ad0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
16ae0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
16af0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
16b00 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
16b10 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
16b20 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
16b30 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
16b40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
16b50 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16b60 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
16b70 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
16b80 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
16b90 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
16ba0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
16bb0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
16bc0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
16bd0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
16be0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
16bf0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
16c00 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
16c10 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
16c20 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
16c30 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
16c40 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
16c50 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
16c60 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
16c70 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
16c80 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
16c90 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
16ca0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
16cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
16cc0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
16cd0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
16ce0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
16cf0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
16d00 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
16d10 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
16d20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
16d30 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
16d40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
16d50 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
16d60 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
16d70 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
16d80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16d90 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
16da0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
16db0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
16dc0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
16dd0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
16de0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
16df0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
16e00 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
16e10 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16e20 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16e30 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16e40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
16e50 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
16e60 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
16e70 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
16e80 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
16e90 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
16ea0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
16eb0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
16ec0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
16ed0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
16ee0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16ef0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16f00 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16f10 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16f20 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16f30 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
16f40 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
16f50 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
16f60 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
16f70 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
16f80 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
16f90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
16fa0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
16fb0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
16fc0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
16fd0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
16fe0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
16ff0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17000 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17010 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17020 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17030 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17040 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
17050 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
17060 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
17070 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17080 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17090 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
170a0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
170b0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
170c0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
170d0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
170e0 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
170f0 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17100 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17110 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17120 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17130 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17140 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17150 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17160 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17170 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17180 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
17190 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
171a0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
171b0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
171c0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
171d0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
171e0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
171f0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17200 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17210 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17220 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17230 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
17240 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
17250 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
17260 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
17270 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
17280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17290 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
172a0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
172b0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
172c0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
172d0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
172e0 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
172f0 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
17300 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
17310 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
17320 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
17330 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
17340 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
17350 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
17360 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
17370 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
17380 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
17390 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
173a0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
173b0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
173c0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
173d0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
173e0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
173f0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
17400 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
17410 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17420 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
17430 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
17440 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
17450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
17460 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
17470 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
17480 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
17490 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
174a0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
174b0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
174c0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
174d0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
174e0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
174f0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
17500 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
17510 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
17520 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
17530 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
17540 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
17550 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
17560 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
17570 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
17580 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
17590 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
175a0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
175b0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
175c0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
175d0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
175e0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
175f0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
17600 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
17610 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
17620 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
17630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
17640 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17650 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72  d(D) interface r
17660 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
17670 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f  d] of the .** mo
17680 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
17690 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
176a0 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
176b0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
176c0 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
176d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
176e0 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74  .** ^Inserts int
176f0 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
17700 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
17710 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49   recorded..** ^I
17720 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
17730 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
17740 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68  owid tables.** h
17750 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
17760 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  d on the databas
17770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  e connection D, 
17780 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
17790 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
177a0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65  id(D) returns ze
177b0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ro..**.** ^(If a
177c0 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
177d0 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
177e0 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
177f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
17800 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
17810 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
17820 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
17830 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
17840 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
17850 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
17860 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17870 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
17880 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
17890 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
178a0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
178b0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
178c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
178d0 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
178e0 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
178f0 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
17900 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17910 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
17920 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
17930 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
17940 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
17950 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
17960 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
17970 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
17980 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
17990 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
179a0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
179b0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
179c0 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
179d0 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
179e0 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
179f0 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
17a00 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
17a10 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
17a20 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
17a30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
17a40 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
17a50 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
17a60 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
17a70 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
17a80 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
17a90 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
17aa0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
17ab0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
17ac0 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
17ad0 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
17ae0 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
17af0 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
17b00 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
17b10 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
17b20 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
17b30 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
17b40 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
17b50 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
17b60 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
17b70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
17b80 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
17b90 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
17ba0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
17bb0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
17bc0 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
17bd0 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
17be0 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
17bf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
17c00 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
17c10 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
17c20 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
17c30 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
17c40 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
17c50 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
17c60 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
17c70 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
17c80 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
17c90 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
17ca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
17cb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
17cc0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17cd0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
17ce0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
17cf0 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
17d00 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
17d10 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
17d20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
17d30 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
17d40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
17d50 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
17d60 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
17d70 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
17d80 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
17d90 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
17da0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
17db0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
17dc0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17dd0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
17de0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17df0 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
17e00 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17e10 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
17e20 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
17e30 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17e40 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
17e50 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20   rows modified, 
17e60 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64  inserted or.** d
17e70 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
17e80 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
17e90 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
17ea0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a  DATE or DELETE.*
17eb0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  * statement on t
17ec0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17ed0 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
17ee0 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   by the only par
17ef0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63  ameter..** ^Exec
17f00 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
17f10 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
17f20 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d  ement does not m
17f30 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a  odify the value.
17f40 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ** returned by t
17f50 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
17f60 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65  .** ^Only change
17f70 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20  s made directly 
17f80 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
17f90 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
17fa0 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a  statement are.**
17fb0 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75   considered - au
17fc0 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
17fd0 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54  caused by [CREAT
17fe0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17ff0 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65  gers], .** [fore
18000 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
18010 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   or [REPLACE] co
18020 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
18030 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ion are not coun
18040 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e  ted..** .** Chan
18050 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
18060 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
18070 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45  ed by .** [INSTE
18080 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20  AD OF trigger | 
18090 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
180a0 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ers] are not cou
180b0 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65  nted. ^The value
180c0 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79   .** returned by
180d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
180e0 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  () immediately a
180f0 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20  fter an INSERT, 
18100 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45  UPDATE or .** DE
18110 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72  LETE statement r
18120 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20  un on a view is 
18130 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c  always zero. Onl
18140 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74  y changes made t
18150 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65  o real .** table
18160 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
18170 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20  *.** Things are 
18180 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
18190 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
181a0 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
181b0 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65  on is.** execute
181c0 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65  d while a trigge
181d0 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e  r program is run
181e0 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68  ning. This may h
181f0 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20  appen if the.** 
18200 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65  program uses the
18210 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
18220 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66  function], or if
18230 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c   some other call
18240 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
18250 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33   invokes sqlite3
18260 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63  _changes() direc
18270 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79  tly. Essentially
18280 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
18290 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65     <li> ^(Before
182a0 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67   entering a trig
182b0 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20  ger program the 
182c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
182d0 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69  y.**        sqli
182e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
182f0 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e  nction is saved.
18300 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67   After the trigg
18310 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20  er program .**  
18320 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68        has finish
18330 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ed, the original
18340 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72   value is restor
18350 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c  ed.)^.** .**   <
18360 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74  li> ^(Within a t
18370 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
18380 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ach INSERT, UPDA
18390 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a  TE and DELETE .*
183a0 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65  *        stateme
183b0 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75  nt sets the valu
183c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
183d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
183e0 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20  .**        upon 
183f0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f  completion as no
18400 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c  rmal. Of course,
18410 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c   this value will
18420 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a   not include .**
18430 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e          any chan
18440 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ges performed by
18450 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61   sub-triggers, a
18460 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  s the sqlite3_ch
18470 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
18480 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65     value will be
18490 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f   saved and resto
184a0 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73  red after each s
184b0 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72  ub-trigger has r
184c0 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  un.)^.** </ul>.*
184d0 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e  * .** ^This mean
184e0 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68  s that if the ch
184f0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18500 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72  tion (or similar
18510 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20  ) is used.** by 
18520 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54  the first INSERT
18530 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18540 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18550 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69  hin a trigger, i
18560 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  t .** returns th
18570 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77  e value as set w
18580 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  hen the calling 
18590 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20  statement began 
185a0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49  executing..** ^I
185b0 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20  f it is used by 
185c0 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75  the second or su
185d0 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74  bsequent such st
185e0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
185f0 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f   trigger .** pro
18600 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20  gram, the value 
18610 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74  returned reflect
18620 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18630 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79  rows modified by
18640 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75   the .** previou
18650 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  s INSERT, UPDATE
18660 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
18670 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
18680 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
18690 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
186a0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
186b0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
186c0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
186d0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
186e0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
186f0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18700 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18710 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18720 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
18730 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
18740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18750 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
18760 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
18770 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
18780 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18790 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
187a0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
187b0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
187c0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
187d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
187e0 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
187f0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
18800 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
18810 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18820 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
18830 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
18840 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
18850 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
18860 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
18870 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
18880 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
18890 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
188a0 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
188b0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
188c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
188d0 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
188e0 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
188f0 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
18900 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
18910 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
18920 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
18930 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
18940 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
18950 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
18960 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
18970 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
18980 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
18990 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
189a0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
189b0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
189c0 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
189d0 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
189e0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
189f0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
18a00 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
18a10 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
18a20 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
18a30 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
18a40 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
18a50 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
18a60 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
18a70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18a80 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18a90 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
18aa0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
18ab0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
18ac0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
18ad0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18ae0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18af0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18b00 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
18b10 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
18b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18b30 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
18b40 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18b50 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
18b60 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
18b70 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
18b80 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
18b90 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
18ba0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
18bb0 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
18bc0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
18bd0 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
18be0 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
18bf0 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Query.** METHOD:
18c00 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18c10 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
18c20 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
18c30 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
18c40 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
18c50 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
18c60 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
18c70 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
18c80 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
18c90 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
18ca0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
18cb0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
18cc0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
18cd0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
18ce0 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
18cf0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
18d00 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
18d10 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
18d20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
18d30 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
18d40 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
18d50 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
18d60 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
18d70 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
18d80 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
18d90 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
18da0 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
18db0 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
18dc0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
18dd0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
18de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18df0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
18e00 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
18e10 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
18e20 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
18e30 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
18e40 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
18e50 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
18e60 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
18e70 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
18e80 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18e90 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
18ea0 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
18eb0 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
18ec0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
18ed0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
18ee0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
18ef0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
18f00 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
18f10 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
18f20 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
18f30 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
18f40 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
18f50 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
18f60 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
18f70 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
18f80 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
18f90 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
18fa0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
18fb0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
18fc0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
18fd0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
18fe0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
18ff0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
19000 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19010 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
19020 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
19030 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
19040 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
19050 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
19060 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19070 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
19080 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
19090 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
190a0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
190b0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
190c0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
190d0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
190e0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
190f0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
19100 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
19110 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
19120 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
19130 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
19140 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
19150 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
19160 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
19170 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
19180 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
19190 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
191a0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
191b0 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
191c0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
191d0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
191e0 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
191f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
19200 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
19210 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
19220 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
19230 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
19240 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
19250 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
19260 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
19270 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
19280 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
19290 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
192a0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
192b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
192c0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
192d0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
192e0 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
192f0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
19300 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
19310 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
19320 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
19330 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
19340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19350 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
19360 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
19370 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
19380 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19390 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
193a0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
193b0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
193c0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
193d0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
193e0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
193f0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
19400 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
19410 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
19420 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
19430 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
19440 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
19450 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
19460 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
19470 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
19480 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
19490 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
194a0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
194b0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
194c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
194d0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
194e0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
194f0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
19500 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
19510 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
19520 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
19530 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
19540 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
19550 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
19560 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
19570 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
19580 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
19590 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
195a0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
195b0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
195c0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
195d0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
195e0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
195f0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
19600 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
19610 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
19620 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
19630 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
19640 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
19650 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
19660 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
19670 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
19680 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
19690 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
196a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
196b0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
196c0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
196d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
196e0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
196f0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
19700 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
19710 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
19720 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
19730 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
19740 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
19750 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
19760 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
19770 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
19780 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
19790 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
197a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
197b0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
197c0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
197d0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
197e0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
197f0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
19800 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
19810 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
19820 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
19830 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
19840 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
19850 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
19860 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
19870 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
19880 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
19890 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
198a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
198b0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
198c0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
198d0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
198e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
198f0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
19900 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19910 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
19920 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
19930 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
19940 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
19950 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19960 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
19970 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
19980 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
19990 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
199a0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
199b0 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
199c0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
199d0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
199e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
199f0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
19a00 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
19a10 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
19a20 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
19a30 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
19a40 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
19a50 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
19a60 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19a70 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19a80 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
19a90 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
19aa0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
19ab0 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
19ac0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
19ad0 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
19ae0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
19af0 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
19b00 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
19b10 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
19b20 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
19b30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
19b40 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
19b50 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
19b60 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
19b70 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
19b80 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19b90 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
19ba0 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
19bb0 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
19bc0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
19bd0 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
19be0 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
19bf0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
19c00 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
19c10 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
19c20 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
19c30 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
19c40 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
19c50 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
19c60 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19c70 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
19c80 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
19c90 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
19ca0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
19cb0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
19cc0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19cd0 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
19ce0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
19cf0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
19d00 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
19d10 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
19d20 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
19d30 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
19d40 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
19d50 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
19d60 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
19d70 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
19d80 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
19d90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19da0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
19db0 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
19dc0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
19dd0 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
19de0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
19df0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
19e00 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
19e10 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
19e20 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
19e30 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
19e40 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
19e50 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
19e60 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
19e70 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
19e80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19e90 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
19ea0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
19eb0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
19ec0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19ed0 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
19ee0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
19ef0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
19f00 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
19f10 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
19f20 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
19f30 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
19f40 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
19f50 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
19f60 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
19f70 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
19f80 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
19f90 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
19fa0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
19fb0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
19fc0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
19fd0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
19fe0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19ff0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1a000 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1a010 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1a020 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1a030 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1a040 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1a050 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1a060 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1a070 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1a080 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1a090 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1a0a0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1a0b0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1a0c0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1a0d0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1a0e0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1a0f0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1a100 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1a110 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1a120 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1a130 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1a140 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1a150 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1a160 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1a170 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1a180 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1a190 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1a1a0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1a1b0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1a1c0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1a1d0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1a1e0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1a1f0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1a200 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1a210 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1a220 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1a230 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1a240 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1a250 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1a260 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1a270 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1a280 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1a290 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1a2a0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1a2b0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1a2c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1a2d0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1a2e0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1a2f0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1a300 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1a310 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1a320 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1a330 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1a340 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1a350 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1a360 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1a370 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1a380 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1a390 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1a3a0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1a3b0 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1a3c0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1a3d0 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1a3e0 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1a3f0 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1a400 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1a410 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1a420 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1a430 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1a440 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1a450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a460 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1a470 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1a480 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1a490 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1a4a0 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1a4b0 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1a4c0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1a4d0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1a4e0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1a4f0 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1a500 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1a510 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a520 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1a530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1a540 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1a550 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1a560 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a570 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1a580 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
1a590 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
1a5a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a5b0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1a5c0 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1a5d0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1a5e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1a5f0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1a600 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1a610 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1a620 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1a630 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1a640 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1a650 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1a660 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1a670 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1a680 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1a690 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1a6a0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1a6b0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1a6c0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1a6d0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1a6e0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1a6f0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1a700 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1a710 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1a720 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1a730 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1a740 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1a750 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1a760 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1a770 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1a780 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1a790 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1a7a0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1a7b0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1a7c0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1a7d0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1a7e0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1a7f0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1a800 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a810 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1a820 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1a830 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1a840 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1a850 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1a860 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1a870 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1a880 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1a890 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1a8a0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1a8b0 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1a8c0 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1a8d0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1a8e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1a8f0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1a900 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1a910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a920 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1a930 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1a940 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1a950 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a960 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1a970 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1a980 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1a990 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1a9a0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1a9b0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1a9c0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1a9d0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1a9e0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1a9f0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1aa00 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1aa10 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1aa20 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1aa30 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1aa40 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1aa50 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1aa60 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1aa70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1aa80 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1aa90 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1aaa0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1aab0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1aac0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1aad0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1aae0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1aaf0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1ab00 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1ab10 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1ab20 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1ab30 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1ab40 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1ab50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1ab60 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1ab70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1ab80 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1ab90 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1aba0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1abb0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1abc0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1abd0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1abe0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1abf0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1ac00 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1ac10 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1ac20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1ac30 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1ac40 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1ac50 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1ac60 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1ac70 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1ac80 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1ac90 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1aca0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1acb0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1acc0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1acd0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1ace0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1acf0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1ad00 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1ad10 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1ad20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1ad30 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1ad40 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1ad50 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1ad60 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1ad70 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1ad80 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1ad90 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1ada0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1adb0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1adc0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1add0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1ade0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1adf0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1ae00 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1ae10 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1ae20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1ae30 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1ae40 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1ae50 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1ae60 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1ae70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1ae80 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1ae90 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1aea0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1aeb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1aec0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1aed0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1aee0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1aef0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1af00 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1af10 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1af20 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1af30 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1af40 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1af50 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1af60 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1af70 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1af80 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1af90 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1afa0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1afb0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1afc0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1afd0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1afe0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1aff0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b000 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1b010 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1b020 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1b030 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1b040 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1b050 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b060 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1b070 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b080 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1b090 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b0a0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1b0b0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1b0c0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1b0d0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1b0e0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1b0f0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1b100 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b110 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1b120 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b130 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1b140 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b150 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1b160 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1b170 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1b180 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1b190 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1b1a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b1b0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1b1c0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1b1d0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1b1e0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1b1f0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1b200 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1b210 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1b220 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1b230 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1b240 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1b250 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1b260 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b270 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1b280 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1b290 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1b2a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b2b0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1b2c0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1b2d0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1b2e0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1b2f0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1b300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1b310 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1b320 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1b330 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1b340 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1b350 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1b360 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1b370 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1b380 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1b390 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1b3a0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1b3b0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1b3c0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1b3d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1b3e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b3f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1b400 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1b410 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1b420 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1b430 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1b440 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1b450 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1b460 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1b470 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1b480 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1b490 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1b4a0 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1b4b0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1b4c0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1b4d0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1b4e0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1b4f0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1b500 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1b510 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1b520 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1b530 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1b540 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1b550 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1b560 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1b570 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1b580 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1b590 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b5a0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1b5b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1b5c0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1b5d0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1b5e0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1b5f0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1b600 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1b610 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1b620 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1b630 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1b640 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1b650 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1b660 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1b670 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1b680 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1b690 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1b6a0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1b6b0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1b6c0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1b6d0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1b6e0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1b6f0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
1b700 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1b710 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1b720 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1b730 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1b740 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1b750 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1b760 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b770 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1b780 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1b790 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1b7a0 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1b7b0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1b7c0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1b7d0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1b7e0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1b7f0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1b800 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1b810 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1b820 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1b830 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1b840 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1b850 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1b860 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1b870 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b880 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1b890 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1b8a0 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1b8b0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1b8c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1b8d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b8e0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1b8f0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1b900 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1b910 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1b920 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1b930 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1b940 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1b950 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1b960 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1b970 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1b980 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1b990 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1b9a0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1b9b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1b9c0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1b9d0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1b9e0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1b9f0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1ba00 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1ba10 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1ba20 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1ba30 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1ba40 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1ba50 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1ba60 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1ba70 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1ba80 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1ba90 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1baa0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1bab0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1bac0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1bad0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1bae0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1baf0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1bb00 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1bb10 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1bb20 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1bb30 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1bb40 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1bb50 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1bb60 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1bb70 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1bb80 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1bb90 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1bba0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1bbb0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1bbc0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1bbd0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1bbe0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1bbf0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1bc00 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1bc10 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1bc20 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1bc30 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1bc40 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1bc50 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1bc60 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1bc70 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1bc80 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1bc90 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1bca0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1bcb0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1bcc0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1bcd0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1bce0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1bcf0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1bd00 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1bd10 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1bd20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1bd30 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1bd40 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1bd50 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1bd60 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1bd70 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1bd80 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1bd90 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1bda0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1bdb0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1bdc0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1bdd0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1bde0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1bdf0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1be00 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1be10 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1be20 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1be30 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1be40 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1be50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1be60 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1be70 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1be80 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1be90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1bea0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1beb0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1bec0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1bed0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1bee0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1bef0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1bf00 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1bf10 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1bf20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1bf30 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1bf40 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1bf50 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1bf60 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1bf70 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1bf80 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1bf90 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1bfa0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1bfb0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1bfc0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1bfd0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1bfe0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1bff0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1c000 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1c010 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1c020 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1c030 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1c040 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1c050 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1c060 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1c070 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1c080 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1c090 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1c0a0 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1c0b0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1c0c0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1c0d0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1c0e0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1c0f0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1c100 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1c110 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1c120 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c130 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1c140 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1c150 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1c160 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c170 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1c180 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1c190 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1c1a0 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1c1b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c1c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1c1d0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1c1e0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1c1f0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1c200 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1c210 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1c220 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1c230 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1c240 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1c250 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1c260 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1c270 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1c280 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1c290 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1c2a0 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1c2b0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1c2c0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1c2d0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1c2e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c2f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c300 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c310 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1c320 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1c330 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c340 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1c350 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1c360 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1c370 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1c380 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1c390 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1c3a0 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1c3b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c3c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1c3d0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1c3e0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1c3f0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1c400 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1c410 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1c420 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1c430 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1c440 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1c450 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1c460 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1c470 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1c480 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1c490 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1c4a0 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1c4b0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1c4c0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1c4d0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1c4e0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1c4f0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1c500 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1c510 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1c520 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1c530 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1c540 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1c550 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1c560 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1c570 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1c580 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1c590 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1c5a0 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1c5b0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1c5c0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1c5d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c5e0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1c5f0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1c600 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c610 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1c620 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1c630 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1c640 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1c650 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1c660 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1c670 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c680 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1c690 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1c6a0 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1c6b0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1c6c0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1c6d0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1c6e0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1c6f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1c700 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1c710 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1c720 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1c730 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1c740 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1c750 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1c760 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1c770 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1c780 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1c790 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1c7a0 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1c7b0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1c7c0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1c7d0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1c7e0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1c7f0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1c800 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1c810 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1c820 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1c830 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1c840 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1c850 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1c860 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1c870 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1c880 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1c890 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1c8a0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1c8b0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1c8c0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1c8d0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1c8e0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1c8f0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1c900 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1c910 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1c920 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1c930 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1c940 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1c950 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1c960 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1c970 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1c980 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1c990 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1c9a0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c9b0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1c9c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c9d0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1c9e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1c9f0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1ca00 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1ca10 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1ca20 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1ca30 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1ca40 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1ca50 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1ca60 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1ca70 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1ca80 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1ca90 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1caa0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1cab0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1cac0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1cad0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1cae0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1caf0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1cb00 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1cb10 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1cb20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1cb30 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1cb40 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1cb50 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1cb60 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1cb70 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1cb80 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1cb90 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1cba0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1cbb0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1cbc0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1cbd0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1cbe0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1cbf0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1cc00 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1cc10 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1cc20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1cc30 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1cc40 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1cc50 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1cc60 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1cc70 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1cc80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1cc90 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1cca0 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1ccb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1ccc0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1ccd0 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1cce0 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1ccf0 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1cd00 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1cd10 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1cd20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1cd30 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1cd40 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1cd50 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1cd60 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1cd70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1cd80 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1cd90 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1cda0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1cdb0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1cdc0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1cdd0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1cde0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1cdf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1ce00 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1ce10 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1ce20 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1ce30 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1ce40 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1ce50 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1ce60 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1ce70 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1ce80 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1ce90 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1cea0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1ceb0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1cec0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1ced0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1cee0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1cef0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1cf00 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1cf10 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1cf20 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1cf30 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1cf40 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1cf50 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1cf60 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1cf70 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1cf80 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1cf90 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1cfa0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1cfb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1cfc0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1cfd0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1cfe0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1cff0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1d000 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1d010 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1d020 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1d030 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d040 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1d050 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1d060 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1d070 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1d080 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1d090 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d0a0 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1d0b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d0c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d0d0 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1d0e0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1d0f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1d100 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1d110 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1d120 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1d130 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1d140 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1d150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1d160 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d170 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1d180 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1d190 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1d1a0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1d1b0 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1d1c0 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1d1d0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1d1e0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1d1f0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1d200 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1d210 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1d220 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1d230 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1d240 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1d250 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d260 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1d270 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1d280 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1d290 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d2a0 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1d2b0 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1d2c0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1d2d0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1d2e0 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1d2f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d300 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1d310 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1d320 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1d330 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1d340 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1d350 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1d360 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1d370 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1d380 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1d390 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1d3a0 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1d3b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1d3c0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1d3d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1d3e0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1d3f0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1d400 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d410 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1d420 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1d430 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d440 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1d450 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1d460 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1d470 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1d480 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1d490 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d4a0 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1d4b0 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1d4c0 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1d4d0 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1d4e0 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1d4f0 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1d500 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1d510 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1d520 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1d530 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1d540 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1d550 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1d560 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1d570 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1d580 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1d590 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1d5a0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1d5b0 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1d5c0 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1d5d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1d5e0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1d5f0 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1d600 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1d610 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1d620 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1d630 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1d640 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1d650 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1d660 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d670 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1d680 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1d690 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1d6a0 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1d6b0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1d6c0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1d6d0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1d6e0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1d6f0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1d700 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1d710 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1d720 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1d730 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1d740 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1d750 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1d760 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1d770 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1d780 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1d790 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1d7a0 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1d7b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1d7c0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1d7d0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1d7e0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1d7f0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1d800 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1d810 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1d820 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1d830 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1d840 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1d850 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1d860 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1d870 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1d880 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1d890 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1d8a0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1d8b0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1d8c0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1d8d0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1d8e0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1d8f0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1d900 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1d910 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1d920 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1d930 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1d940 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1d950 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1d960 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1d970 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1d980 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1d990 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1d9a0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1d9b0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1d9c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1d9d0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1d9e0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1d9f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1da00 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1da10 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1da20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1da30 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1da40 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1da50 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1da60 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1da70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1da80 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1da90 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1daa0 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1dab0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1dac0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1dad0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1dae0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1daf0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1db00 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1db10 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1db20 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1db30 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1db40 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1db50 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1db60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1db70 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1db80 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1db90 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1dba0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1dbb0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1dbc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1dbd0 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1dbe0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1dbf0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1dc00 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
1dc10 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1dc20 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1dc30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1dc40 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1dc50 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1dc60 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1dc70 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1dc80 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1dc90 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1dca0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1dcb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1dcc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1dcd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1dce0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1dcf0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1dd00 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1dd10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1dd20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1dd30 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1dd40 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1dd50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1dd60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1dd70 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1dd80 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1dd90 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1dda0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1ddb0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1ddc0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1ddd0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1dde0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1ddf0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1de00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1de10 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1de20 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1de30 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1de40 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1de50 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1de60 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1de70 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1de80 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1de90 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1dea0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1deb0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1dec0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1ded0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1dee0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1def0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1df00 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1df10 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1df20 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1df30 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1df40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1df50 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1df60 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1df70 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1df80 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1df90 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1dfa0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1dfb0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1dfc0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1dfd0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1dfe0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1dff0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1e000 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1e010 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1e020 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e030 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1e040 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1e050 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1e060 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1e070 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1e080 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1e090 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1e0a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e0b0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1e0c0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1e0d0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1e0e0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1e0f0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1e100 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1e110 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1e120 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1e130 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1e140 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1e150 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1e160 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1e170 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1e180 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1e190 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1e1a0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1e1b0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1e1c0 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1e1d0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1e1e0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1e1f0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1e200 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1e210 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1e220 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1e230 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1e240 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1e250 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1e260 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1e270 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1e280 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1e290 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1e2a0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1e2b0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
1e2c0 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
1e2d0 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
1e2e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
1e2f0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
1e300 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
1e310 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
1e320 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
1e330 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
1e340 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
1e350 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
1e360 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
1e370 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
1e380 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1e390 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
1e3a0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1e3b0 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
1e3c0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1e3d0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1e3e0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
1e3f0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1e400 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
1e410 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
1e420 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
1e430 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
1e440 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1e450 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1e460 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1e470 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1e480 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1e490 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1e4a0 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
1e4b0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1e4c0 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1e4d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e4e0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1e4f0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1e500 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
1e510 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1e520 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1e530 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1e540 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e550 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1e560 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1e570 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1e580 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1e590 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1e5a0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1e5b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1e5c0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1e5d0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1e5e0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1e5f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1e600 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1e610 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1e620 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1e630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1e640 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e650 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1e660 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1e670 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1e680 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1e690 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1e6a0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1e6b0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1e6c0 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1e6d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e6e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1e6f0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1e700 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1e710 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1e720 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e730 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1e740 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1e750 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1e760 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1e770 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1e780 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1e790 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1e7a0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1e7b0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1e7c0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1e7d0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1e7e0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1e7f0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1e800 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1e810 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1e820 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1e830 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e840 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1e850 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1e860 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1e870 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1e880 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1e890 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1e8a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1e8b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1e8c0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1e8d0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1e8e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1e8f0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1e900 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1e910 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1e920 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1e930 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1e940 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1e950 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1e960 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1e970 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1e980 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1e990 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1e9a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e9b0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1e9c0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1e9d0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1e9e0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1e9f0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1ea00 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1ea10 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1ea20 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1ea30 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1ea40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1ea50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ea60 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1ea70 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1ea80 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1ea90 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1eaa0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1eab0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1eac0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1ead0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1eae0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1eaf0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1eb00 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1eb10 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1eb20 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1eb30 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1eb40 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1eb50 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1eb60 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1eb70 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1eb80 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1eb90 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1eba0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1ebb0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1ebc0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1ebd0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1ebe0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1ebf0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1ec00 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1ec10 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1ec20 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1ec30 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1ec40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1ec50 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1ec60 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1ec70 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1ec80 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1ec90 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1eca0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1ecb0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1ecc0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1ecd0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1ece0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1ecf0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1ed00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1ed10 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1ed20 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1ed30 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1ed40 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1ed50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1ed60 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1ed70 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1ed80 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1ed90 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1eda0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1edb0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1edc0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1edd0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1ede0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1edf0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1ee00 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1ee10 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1ee20 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1ee30 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1ee40 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1ee50 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1ee60 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1ee70 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1ee80 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1ee90 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1eea0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1eeb0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1eec0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1eed0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1eee0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1eef0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1ef00 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1ef10 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1ef20 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1ef30 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1ef40 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1ef50 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1ef60 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1ef70 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1ef80 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1ef90 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1efa0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1efb0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1efc0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1efd0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1efe0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1eff0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1f000 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1f010 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1f020 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1f030 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1f040 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1f050 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1f060 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1f070 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1f080 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1f090 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1f0a0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1f0b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1f0c0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1f0d0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1f0e0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1f0f0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1f100 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1f110 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1f120 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1f130 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1f140 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1f150 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1f160 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1f170 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1f180 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1f190 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1f1a0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1f1b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1f1c0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1f1d0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1f1e0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1f1f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1f200 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1f210 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1f220 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1f230 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1f240 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1f250 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1f260 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1f270 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1f280 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1f290 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1f2a0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1f2b0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1f2c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f2d0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1f2e0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1f2f0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1f300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f310 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1f320 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f330 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1f340 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1f350 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1f360 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f370 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1f380 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1f390 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1f3a0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1f3b0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1f3c0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1f3d0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1f3e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1f3f0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1f400 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1f410 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1f420 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1f430 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1f440 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1f450 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1f460 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1f470 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1f480 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1f490 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1f4a0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1f4b0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1f4c0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1f4d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1f4e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1f4f0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1f500 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1f510 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1f520 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1f530 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1f540 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1f550 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1f560 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1f570 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1f580 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1f590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1f5a0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1f5b0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1f5c0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1f5d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1f5e0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1f5f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1f600 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1f610 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1f620 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1f630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1f640 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1f650 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1f660 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1f670 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1f680 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1f690 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1f6a0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1f6b0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1f6c0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1f6d0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1f6e0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1f6f0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f700 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1f710 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f720 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1f730 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1f740 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1f750 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1f760 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1f770 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1f780 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1f790 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1f7a0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1f7b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1f7c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1f7d0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1f7e0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1f7f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1f800 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1f810 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1f820 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1f830 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
1f840 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
1f850 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
1f860 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1f870 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1f880 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1f890 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f8a0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1f8b0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1f8c0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1f8d0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1f8e0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1f8f0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1f900 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1f910 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1f920 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1f930 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1f940 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1f950 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1f960 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f970 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1f980 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1f990 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1f9a0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1f9b0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1f9c0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1f9d0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1f9e0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1f9f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1fa00 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1fa10 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1fa20 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1fa30 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1fa40 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1fa50 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1fa60 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1fa70 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1fa80 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1fa90 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1faa0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1fab0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1fac0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1fad0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1fae0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1faf0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1fb00 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1fb10 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1fb20 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1fb30 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1fb40 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1fb50 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1fb60 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1fb70 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1fb80 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1fb90 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1fba0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1fbb0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1fbc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1fbd0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1fbe0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1fbf0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1fc00 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1fc10 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1fc20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1fc30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fc40 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1fc50 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1fc60 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1fc70 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1fc80 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1fc90 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1fca0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1fcb0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1fcc0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1fcd0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1fce0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1fcf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fd00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fd10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1fd20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1fd30 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1fd40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fd50 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1fd60 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1fd70 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1fd80 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fd90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fda0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1fdb0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1fdc0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1fdd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fde0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fdf0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1fe00 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1fe10 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1fe20 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1fe30 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fe40 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1fe50 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1fe60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1fe70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1fe80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1fe90 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1fea0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1feb0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1fec0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fed0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1fee0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1fef0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ff00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ff10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ff20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1ff30 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1ff40 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ff50 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ff60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ff70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1ff80 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1ff90 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ffa0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ffb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ffc0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1ffd0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1ffe0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1fff0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20000 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20010 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
20020 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
20030 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20040 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20050 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20060 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
20070 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
20080 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20090 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
200a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
200b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
200c0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
200d0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
200e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
200f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20100 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
20110 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
20120 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20130 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20140 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20150 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
20160 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
20170 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
20180 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
201a0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
201b0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
201c0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
201d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
201e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
201f0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
20200 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
20210 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
20220 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20240 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
20250 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
20260 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20270 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20280 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
20290 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
202a0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
202b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
202c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
202d0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
202e0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
202f0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
20300 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
20310 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
20320 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
20330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20340 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
20350 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
20360 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20370 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
20380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
20390 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
203a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
203b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
203c0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
203d0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
203e0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
203f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20400 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20410 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
20420 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
20430 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20440 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
20450 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20460 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
20470 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
20480 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
20490 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
204a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
204b0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
204c0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
204d0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
204e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
204f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20500 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
20510 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
20520 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
20530 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20550 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
20560 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
20570 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
20580 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
205a0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
205b0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
205c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
205d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
205e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
205f0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
20600 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
20610 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
20620 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
20630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20640 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
20650 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
20660 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
20670 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
20680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
20690 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
206a0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
206b0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
206c0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
206d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
206e0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
206f0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
20700 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
20710 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
20720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
20730 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
20740 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
20750 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
20760 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
20770 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
20780 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
20790 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
207a0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
207b0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
207c0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
207d0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
207e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
207f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20800 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
20810 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
20820 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
20830 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
20840 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
20850 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
20860 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
20870 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
20880 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
20890 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
208a0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
208b0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
208c0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
208d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
208e0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
208f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
20900 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20910 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
20920 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
20930 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
20940 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
20950 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
20960 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
20970 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
20980 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
20990 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
209a0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
209b0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
209c0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
209d0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
209e0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
209f0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
20a00 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
20a10 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
20a20 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
20a30 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
20a40 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
20a50 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
20a60 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
20a70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
20a80 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
20a90 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
20aa0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
20ab0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
20ac0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
20ad0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
20af0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
20b00 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
20b10 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
20b20 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
20b30 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
20b40 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
20b50 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20b60 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
20b70 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
20b80 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
20b90 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
20ba0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
20bb0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
20bc0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
20bd0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
20be0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
20bf0 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
20c00 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
20c10 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
20c20 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
20c30 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
20c40 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
20c50 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
20c60 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
20c70 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
20c80 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
20c90 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
20ca0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
20cb0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
20cc0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
20cd0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
20ce0 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
20cf0 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
20d00 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
20d10 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
20d20 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
20d30 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
20d40 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
20d50 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
20d60 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20d70 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
20d80 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
20d90 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
20da0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
20db0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
20dc0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
20dd0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
20de0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
20df0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
20e00 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
20e10 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
20e20 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
20e30 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
20e40 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
20e50 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
20e60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
20e70 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
20e80 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
20e90 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
20ea0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
20eb0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
20ec0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
20ed0 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
20ee0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
20ef0 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
20f00 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
20f10 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
20f20 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
20f30 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
20f40 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
20f50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20f60 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
20f70 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
20f80 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
20f90 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
20fa0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
20fb0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
20fc0 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
20fd0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
20fe0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
20ff0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
21000 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21010 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
21020 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
21030 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
21040 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
21050 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
21060 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
21070 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
21080 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
21090 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
210a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
210b0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
210c0 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
210d0 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
210e0 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
210f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
21100 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
21110 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
21120 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
21130 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
21140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21150 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
21160 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
21170 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
21180 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
21190 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
211a0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
211b0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
211c0 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
211d0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
211e0 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
211f0 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
21200 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
21210 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
21220 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
21230 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
21240 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
21250 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
21260 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
21270 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
21280 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
21290 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
212a0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
212b0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
212c0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
212d0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
212e0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
212f0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
21300 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
21310 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21320 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
21330 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
21340 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
21350 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
21360 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21370 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
21380 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
21390 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
213a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
213b0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
213c0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
213d0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
213e0 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
213f0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
21400 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
21410 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
21420 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
21430 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
21440 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
21450 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
21460 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
21470 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
21480 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
21490 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
214a0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
214b0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
214c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
214d0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
214e0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
214f0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
21500 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
21510 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21520 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
21530 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
21540 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
21550 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
21560 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
21570 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21580 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
21590 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
215a0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
215b0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
215c0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
215d0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
215e0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
215f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
21600 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
21610 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
21620 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
21630 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
21640 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
21650 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
21660 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
21670 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
21680 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
21690 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
216a0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
216b0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
216c0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
216d0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
216e0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
216f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21700 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
21710 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
21720 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
21730 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
21740 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
21750 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
21760 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
21770 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
21780 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
21790 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
217a0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
217b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
217c0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
217d0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
217e0 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
217f0 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
21800 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
21810 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21820 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21830 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
21840 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
21850 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
21860 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
21870 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
21880 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
21890 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
218a0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
218b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
218c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
218d0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
218e0 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
218f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
21900 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21910 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
21920 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
21930 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
21940 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
21950 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
21960 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
21970 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
21980 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21990 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
219a0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
219b0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
219c0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
219d0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
219e0 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
219f0 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
21a00 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
21a10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21a20 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
21a30 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
21a40 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
21a50 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
21a60 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
21a70 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
21a80 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
21a90 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
21aa0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
21ab0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
21ac0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
21ad0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
21ae0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
21af0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21b00 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
21b10 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
21b20 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
21b30 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
21b40 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
21b50 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
21b60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21b70 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
21b80 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
21b90 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
21ba0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
21bb0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
21bc0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
21bd0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
21be0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21bf0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
21c00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
21c10 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21c20 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
21c30 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
21c40 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
21c50 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
21c60 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
21c70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
21c80 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
21c90 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
21ca0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
21cb0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
21cc0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
21cd0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
21ce0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
21cf0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21d00 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
21d10 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
21d20 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
21d30 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
21d40 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21d50 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
21d60 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
21d70 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
21d80 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
21d90 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
21da0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
21db0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
21dc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
21dd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
21de0 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
21df0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
21e00 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
21e10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21e20 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
21e30 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
21e40 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
21e50 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
21e60 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
21e70 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
21e80 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
21e90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
21ea0 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
21eb0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
21ec0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
21ed0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21ee0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
21ef0 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
21f00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21f10 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
21f20 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
21f30 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
21f40 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
21f50 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
21f60 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
21f70 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
21f80 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
21f90 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
21fa0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
21fb0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
21fc0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
21fd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21fe0 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
21ff0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
22000 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
22010 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
22020 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
22030 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
22040 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
22050 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
22060 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
22070 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22080 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
22090 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
220a0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
220b0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
220c0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
220d0 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
220e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
220f0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
22100 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
22110 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
22120 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
22130 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
22140 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22150 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
22160 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
22170 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
22180 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
22190 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
221a0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
221b0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
221c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
221d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
221e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
221f0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22200 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22210 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
22220 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
22230 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
22240 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
22250 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
22260 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
22270 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
22280 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22290 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
222a0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
222b0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
222c0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
222d0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
222e0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
222f0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
22300 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
22310 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
22320 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
22330 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
22340 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
22350 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
22360 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
22370 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
22380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22390 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
223a0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
223b0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
223c0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
223d0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
223e0 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
223f0 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
22400 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
22410 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
22420 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
22430 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
22440 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
22450 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
22460 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
22470 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
22480 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
22490 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
224a0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
224b0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
224c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
224d0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
224e0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
224f0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
22500 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
22510 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
22520 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
22530 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
22540 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
22550 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
22560 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
22570 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22580 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
22590 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
225a0 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
225b0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
225c0 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
225d0 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
225e0 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
225f0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
22600 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
22610 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
22620 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
22630 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
22640 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
22650 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
22660 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
22670 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
22680 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
22690 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
226a0 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
226b0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
226c0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
226d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
226e0 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
226f0 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
22700 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
22710 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
22720 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
22730 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
22740 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
22750 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
22760 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
22770 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
22780 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
22790 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
227a0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
227b0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
227c0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
227d0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
227e0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
227f0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
22800 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
22810 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
22820 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
22830 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
22840 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
22850 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
22860 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
22870 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
22880 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
22890 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
228a0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
228b0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
228c0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
228d0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
228e0 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
228f0 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
22900 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
22910 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
22920 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22930 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
22940 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
22950 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
22960 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
22970 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
22980 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
22990 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
229a0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
229b0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
229c0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
229d0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
229e0 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
229f0 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
22a00 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
22a10 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
22a20 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
22a30 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
22a40 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
22a50 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
22a60 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
22a70 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
22a80 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
22a90 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
22aa0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
22ab0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
22ac0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
22ad0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
22ae0 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
22af0 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
22b00 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
22b10 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
22b20 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
22b30 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
22b40 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
22b50 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
22b60 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
22b70 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
22b80 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
22b90 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
22ba0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
22bb0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
22bc0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
22bd0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
22be0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
22bf0 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
22c00 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
22c10 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
22c20 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
22c30 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
22c40 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
22c50 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
22c60 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
22c70 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
22c80 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
22c90 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
22ca0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
22cb0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
22cc0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
22cd0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
22ce0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
22cf0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
22d00 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
22d10 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
22d20 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
22d30 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
22d40 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
22d50 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
22d60 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
22d70 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
22d80 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
22d90 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
22da0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
22db0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
22dc0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
22dd0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
22de0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
22df0 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
22e00 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
22e10 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
22e20 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
22e30 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
22e40 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
22e50 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
22e60 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
22e70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
22e80 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22e90 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
22ea0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
22eb0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
22ec0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
22ed0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
22ee0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
22ef0 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
22f00 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
22f10 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
22f20 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
22f30 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
22f40 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
22f50 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
22f60 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
22f70 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22f80 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
22f90 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
22fa0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
22fb0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
22fc0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
22fd0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
22fe0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
22ff0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
23000 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
23010 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
23020 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
23030 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
23040 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
23050 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
23060 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
23070 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
23080 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
23090 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
230a0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
230b0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
230c0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
230d0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
230e0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
230f0 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
23100 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23110 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
23120 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
23130 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
23140 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
23150 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
23160 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
23170 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
23180 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
23190 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
231a0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
231b0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
231c0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
231d0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
231e0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
231f0 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
23200 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
23210 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
23220 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
23230 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
23240 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23250 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
23260 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
23270 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
23280 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
23290 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
232a0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
232b0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
232c0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
232d0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
232e0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
232f0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
23300 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
23310 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
23320 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
23330 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
23340 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
23350 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
23360 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
23370 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
23380 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
23390 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
233a0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
233b0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
233c0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
233d0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
233e0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
233f0 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
23400 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
23410 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
23420 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
23430 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
23440 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
23450 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
23460 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
23470 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
23480 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
23490 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
234a0 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
234b0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
234c0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
234d0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
234e0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
234f0 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
23500 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
23510 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
23520 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
23530 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
23540 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
23550 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23560 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
23570 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
23580 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
23590 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
235a0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
235b0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
235c0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
235d0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
235e0 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
235f0 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
23600 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
23610 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
23620 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
23630 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
23640 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
23650 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
23660 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
23670 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
23680 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
23690 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
236a0 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
236b0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
236c0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
236d0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
236e0 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
236f0 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
23700 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
23710 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
23720 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
23730 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
23740 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
23750 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
23760 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
23770 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23780 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
23790 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
237a0 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
237b0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
237c0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
237d0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
237e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
237f0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
23800 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
23810 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
23820 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
23830 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
23840 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
23850 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
23860 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
23870 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
23880 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
23890 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
238a0 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
238b0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
238c0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
238d0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
238e0 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
238f0 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
23900 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
23910 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
23920 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
23930 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
23940 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
23950 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
23960 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
23970 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
23980 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
23990 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
239a0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
239b0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
239c0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
239d0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
239e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
239f0 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
23a00 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
23a10 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
23a20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
23a30 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
23a40 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
23a50 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
23a60 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
23a70 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
23a80 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
23a90 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
23aa0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
23ab0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
23ac0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
23ad0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
23ae0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
23af0 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
23b00 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
23b10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23b20 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
23b30 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23b40 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
23b50 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
23b60 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
23b70 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
23b80 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23b90 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
23ba0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
23bb0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
23bc0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
23bd0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
23be0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23bf0 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
23c00 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
23c10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
23c20 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23c30 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
23c40 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
23c50 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23c60 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
23c70 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
23c80 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
23c90 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
23ca0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
23cb0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
23cc0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
23cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
23ce0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
23cf0 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
23d00 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
23d10 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
23d20 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
23d30 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
23d40 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
23d50 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
23d60 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
23d70 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
23d80 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
23d90 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
23da0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
23db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
23dc0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
23dd0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
23de0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
23df0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
23e00 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
23e10 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
23e20 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
23e30 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
23e40 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
23e50 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
23e60 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
23e70 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
23e80 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
23e90 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
23ea0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
23eb0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
23ec0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
23ed0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
23ee0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
23ef0 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
23f00 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
23f10 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
23f20 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
23f30 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
23f40 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
23f50 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
23f60 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
23f70 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
23f80 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
23f90 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
23fa0 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
23fb0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
23fc0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
23fd0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23fe0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
23ff0 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
24000 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
24010 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
24020 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
24030 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
24040 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
24050 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
24060 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
24070 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
24080 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
24090 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
240a0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
240b0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
240c0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
240d0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
240e0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
240f0 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
24100 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
24110 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
24120 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
24130 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
24140 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
24150 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
24160 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
24170 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
24180 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
24190 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
241a0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
241b0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
241c0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
241d0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
241e0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
241f0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
24200 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
24210 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
24220 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
24230 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
24240 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
24250 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
24260 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
24270 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
24280 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
24290 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
242a0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
242b0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
242c0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
242d0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
242e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
242f0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
24300 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
24310 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
24320 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
24330 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
24340 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
24350 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
24360 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
24370 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
24380 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
24390 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
243a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
243b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
243c0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
243d0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
243e0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
243f0 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
24400 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
24410 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
24420 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
24430 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
24440 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24450 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
24460 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
24470 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
24480 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
24490 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
244a0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
244b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
244c0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
244d0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
244e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
244f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
24500 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24510 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
24520 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
24530 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
24540 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
24550 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
24560 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
24570 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
24580 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
24590 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
245a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
245b0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
245c0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
245d0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
245e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
245f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
24600 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
24610 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24620 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
24630 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
24640 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
24650 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
24660 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
24670 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
24680 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
24690 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
246a0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
246b0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
246c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
246d0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
246e0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
246f0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
24700 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
24710 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
24720 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
24730 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
24740 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
24750 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
24760 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
24770 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
24780 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
24790 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
247a0 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
247b0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
247c0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
247d0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
247e0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
247f0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
24800 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
24810 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
24820 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
24830 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
24840 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
24850 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
24860 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
24870 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24880 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
24890 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
248a0 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
248b0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
248c0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
248d0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
248e0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
248f0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
24900 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
24910 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
24920 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
24930 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
24940 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
24950 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
24960 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
24970 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
24980 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
24990 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
249a0 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
249b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
249c0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
249d0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
249e0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
249f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
24a00 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24a10 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
24a20 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
24a30 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
24a40 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
24a50 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
24a60 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
24a70 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
24a80 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  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 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
24ac0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
24ad0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
24ae0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
24af0 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
24b00 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
24b10 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
24b20 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
24b30 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
24b40 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
24b50 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
24b60 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
24b70 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
24b80 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
24b90 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
24ba0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
24bb0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
24bc0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
24bd0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
24be0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
24bf0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
24c00 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
24c10 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
24c20 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
24c30 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
24c40 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
24c50 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
24c60 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
24c70 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
24c80 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
24c90 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
24ca0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24cb0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
24cc0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
24cd0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
24ce0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
24cf0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
24d00 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
24d10 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
24d20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
24d30 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
24d40 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
24d50 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
24d60 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
24d70 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
24d80 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
24d90 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
24da0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
24db0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24dc0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
24dd0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
24de0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24df0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
24e00 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
24e10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
24e20 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
24e30 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
24e40 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
24e50 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
24e60 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
24e70 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
24e80 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24e90 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
24ea0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
24eb0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
24ec0 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
24ed0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24ee0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
24ef0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
24f00 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
24f10 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
24f20 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24f30 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
24f40 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
24f50 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
24f60 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
24f70 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
24f80 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
24f90 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
24fa0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
24fb0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
24fc0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
24fd0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
24fe0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
24ff0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
25000 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
25010 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
25020 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
25030 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
25040 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
25050 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
25060 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
25070 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
25080 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
25090 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
250a0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
250b0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
250c0 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
250d0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
250e0 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20  nt API call was 
250f0 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74  successful,.** t
25100 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
25110 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
25120 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
25130 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68  ndefined..** ^Th
25140 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
25150 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
25160 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
25170 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
25180 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
25190 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
251a0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
251b0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
251c0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
251d0 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
251e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
251f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
25200 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
25210 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
25220 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
25230 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
25240 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
25250 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
25260 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
25270 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
25280 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
25290 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
252a0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
252b0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
252c0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
252d0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
252e0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
252f0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
25300 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
25310 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
25320 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
25330 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
25340 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
25350 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
25360 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
25370 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
25380 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25390 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
253a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
253b0 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
253c0 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
253d0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
253e0 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
253f0 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
25400 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
25410 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
25420 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
25430 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
25440 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
25450 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
25460 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
25470 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
25480 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
25490 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
254a0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
254b0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
254c0 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
254d0 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
254e0 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
254f0 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
25500 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
25510 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
25520 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
25530 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
25540 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
25550 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
25560 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
25570 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
25580 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
25590 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
255a0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
255b0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
255c0 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
255d0 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
255e0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
255f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25600 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
25610 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
25620 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
25630 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
25640 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
25650 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
25660 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
25670 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
25680 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
25690 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
256a0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
256b0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
256c0 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
256d0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
256e0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
256f0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
25700 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
25710 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
25720 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
25730 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
25740 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
25750 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
25760 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
25770 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
25780 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
25790 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
257a0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
257b0 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
257c0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
257d0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
257e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
257f0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
25800 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
25810 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
25820 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
25830 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25840 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
25850 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25860 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
25870 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
25880 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
25890 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
258a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
258b0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
258c0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
258d0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
258e0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
258f0 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
25900 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
25910 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
25920 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
25930 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
25940 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
25950 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
25960 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
25970 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
25980 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
25990 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
259a0 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
259b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
259c0 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
259d0 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
259e0 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
259f0 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
25a00 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
25a10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25a20 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
25a30 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
25a40 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
25a50 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25a60 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
25a70 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
25a80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
25a90 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
25aa0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25ab0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
25ac0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25ad0 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
25ae0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
25af0 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
25b00 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
25b10 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
25b20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
25b30 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
25b40 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
25b50 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
25b60 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
25b70 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
25b80 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25b90 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
25ba0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
25bb0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
25bc0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
25bd0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
25be0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
25bf0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
25c00 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
25c10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
25c20 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
25c30 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
25c40 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
25c50 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
25c60 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
25c70 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
25c80 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
25c90 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
25ca0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
25cb0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
25cc0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
25cd0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
25ce0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
25cf0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
25d00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
25d10 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
25d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25d30 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
25d40 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
25d50 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
25d60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
25d70 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
25d80 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
25d90 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
25da0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
25db0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
25dc0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
25dd0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
25de0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
25df0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
25e00 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
25e10 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
25e20 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
25e30 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
25e40 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
25e50 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
25e60 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
25e70 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
25e80 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
25e90 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
25ea0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
25eb0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
25ec0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
25ed0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
25ee0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
25ef0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
25f00 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
25f10 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
25f20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
25f30 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
25f40 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
25f50 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
25f60 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
25f70 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25f80 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
25f90 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
25fa0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
25fb0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
25fc0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
25fd0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
25fe0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
25ff0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
26000 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
26010 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
26020 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
26030 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
26040 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
26050 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
26060 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
26070 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
26080 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
26090 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
260a0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
260b0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
260c0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
260d0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
260e0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
260f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
26100 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
26110 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
26120 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
26130 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
26140 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
26150 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
26160 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
26170 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
26180 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
26190 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
261a0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
261b0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
261c0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
261d0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
261e0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
261f0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
26200 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
26210 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
26220 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
26230 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
26240 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
26250 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
26260 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
26270 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
26280 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
26290 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
262a0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
262b0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
262c0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
262d0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
262e0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
262f0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
26300 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
26310 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
26320 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
26330 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
26340 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
26350 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
26360 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
26370 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
26380 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
26390 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
263a0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
263b0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
263c0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
263d0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
263e0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
263f0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
26400 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
26410 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
26420 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
26430 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
26440 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
26450 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
26460 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
26470 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
26480 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
26490 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
264a0 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
264b0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
264c0 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
264d0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
264e0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
264f0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
26500 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
26510 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
26520 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
26530 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
26540 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
26550 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
26560 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
26570 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
26580 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
26590 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
265a0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
265b0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
265c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
265d0 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
265e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
265f0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26600 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
26610 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
26620 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
26630 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
26640 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
26650 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
26660 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
26670 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
26680 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
26690 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
266a0 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
266b0 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
266c0 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
266d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
266e0 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
266f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
26700 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
26710 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26720 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26730 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
26740 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
26750 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
26760 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
26770 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26780 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
26790 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
267a0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
267b0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
267c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
267d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
267e0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
267f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
26800 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
26810 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
26820 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
26830 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
26840 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
26850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26860 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
26870 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
26880 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26890 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
268a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
268b0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
268c0 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
268d0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
268e0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
268f0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
26900 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
26910 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
26920 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
26930 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26940 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
26950 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
26960 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
26970 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
26980 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
26990 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
269a0 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
269b0 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
269c0 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
269d0 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
269e0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
269f0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
26a00 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26a10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
26a20 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
26a30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
26a40 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
26a50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26a60 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
26a70 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
26a80 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
26a90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26aa0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
26ab0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26ac0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
26ad0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26ae0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
26af0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
26b00 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
26b10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
26b20 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
26b30 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
26b40 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26b50 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
26b60 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
26b70 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
26b80 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
26b90 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
26ba0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
26bb0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
26bc0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
26bd0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26be0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
26bf0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
26c00 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
26c10 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
26c20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26c30 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
26c40 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
26c50 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
26c60 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
26c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
26c80 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
26c90 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
26ca0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
26cb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26cc0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
26cd0 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
26ce0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
26cf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26d00 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
26d10 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26d20 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
26d30 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
26d40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26d50 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
26d60 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
26d70 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
26d80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26d90 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
26da0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
26db0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
26dc0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
26dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26de0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
26df0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
26e00 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
26e10 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
26e20 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
26e30 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
26e40 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
26e50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
26e60 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
26e70 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
26e80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
26e90 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
26ea0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
26eb0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
26ec0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
26ed0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
26ee0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
26ef0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
26f00 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
26f10 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26f20 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
26f30 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
26f40 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26f50 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
26f60 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
26f70 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26f80 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
26f90 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#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 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
26fc0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
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 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
26ff0 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
27000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27010 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
27020 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
27030 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
27040 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
27050 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
27060 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
27070 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
27080 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
27090 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
270a0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
270b0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
270c0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
270d0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
270e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
270f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
27100 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
27110 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
27120 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
27130 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
27140 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
27150 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
27160 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
27170 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
27180 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
27190 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
271a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
271b0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
271c0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
271d0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
271e0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
271f0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
27200 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
27210 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
27220 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
27230 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
27240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
27250 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27260 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
27270 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
27280 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
27290 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
272a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
272b0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
272c0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
272d0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
272e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
272f0 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
27300 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
27310 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
27320 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
27330 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
27340 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
27350 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
27360 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
27370 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
27380 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
27390 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
273a0 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
273b0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
273c0 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
273d0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
273e0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
273f0 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
27400 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
27410 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
27420 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
27430 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
27440 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
27450 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
27460 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
27470 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
27480 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
27490 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
274a0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
274b0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
274c0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
274d0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
274e0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
274f0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
27500 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
27510 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
27520 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
27530 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
27540 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
27550 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
27560 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
27570 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
27580 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
27590 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
275a0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
275b0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
275c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
275d0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
275e0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
275f0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
27600 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
27610 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
27620 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
27630 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
27640 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
27650 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
27660 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
27670 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
27680 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
27690 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
276a0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
276b0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
276c0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
276d0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
276e0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
276f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
27700 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
27710 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
27720 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
27730 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
27740 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
27750 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
27760 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
27770 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
27780 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
27790 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
277a0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
277b0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
277c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
277d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
277e0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
277f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27800 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
27810 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
27820 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
27830 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
27840 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
27850 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
27860 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
27870 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
27880 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
27890 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
278a0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
278b0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
278c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
278d0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
278e0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
278f0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
27900 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
27910 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
27920 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
27930 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
27940 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
27950 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
27960 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
27970 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
27980 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
27990 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
279a0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
279b0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
279c0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
279d0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
279e0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
279f0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
27a00 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
27a10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
27a20 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
27a30 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
27a40 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
27a50 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
27a60 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
27a70 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
27a80 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
27a90 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
27aa0 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
27ab0 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
27ac0 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
27ad0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
27ae0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
27af0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
27b00 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
27b10 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
27b20 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
27b30 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
27b40 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
27b50 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
27b60 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
27b70 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27b80 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
27b90 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
27ba0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
27bb0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
27bc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27bd0 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
27be0 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
27bf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
27c00 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
27c10 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
27c20 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
27c30 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
27c40 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
27c50 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
27c60 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
27c70 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
27c80 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
27c90 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
27ca0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
27cb0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
27cc0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
27cd0 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
27ce0 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
27cf0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
27d00 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
27d10 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
27d20 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
27d30 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
27d40 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
27d50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
27d60 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
27d70 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
27d80 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
27d90 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
27da0 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
27db0 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
27dc0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
27dd0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
27de0 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
27df0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
27e00 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
27e10 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
27e20 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
27e30 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
27e40 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
27e50 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
27e60 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
27e70 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
27e80 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
27e90 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
27ea0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
27eb0 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
27ec0 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
27ed0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
27ee0 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
27ef0 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
27f00 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
27f10 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
27f20 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
27f30 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
27f40 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
27f50 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
27f60 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
27f70 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
27f80 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
27f90 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27fa0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
27fb0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27fc0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
27fd0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
27fe0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
27ff0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28000 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28010 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28020 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28030 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28040 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28050 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
28060 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28070 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28080 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28090 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
280a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
280b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
280c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
280d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
280e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
280f0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
28100 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
28110 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
28120 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
28130 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
28140 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
28150 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
28160 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
28170 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
28180 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
28190 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
281a0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
281b0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
281c0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
281d0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
281e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
281f0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
28200 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28210 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28220 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
28230 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
28240 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
28250 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
28260 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
28270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
28280 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
28290 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
282a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
282b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
282c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
282d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
282e0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
282f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
28300 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
28310 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
28320 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
28330 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
28340 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28350 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28360 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28370 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28380 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28390 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
283a0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
283b0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
283c0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
283d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
283e0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
283f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28400 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28410 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28420 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28430 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28440 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28450 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28460 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
28470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28480 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
28490 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
284a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
284b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
284c0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
284d0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
284e0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
284f0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
28500 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
28510 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
28520 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
28530 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
28540 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
28550 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
28560 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28570 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
28580 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
28590 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
285a0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
285b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
285c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
285d0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
285e0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
285f0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
28600 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
28610 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
28620 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
28630 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
28640 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28650 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
28660 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
28670 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
28680 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
28690 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
286a0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
286b0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
286c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
286d0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
286e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
286f0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
28700 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
28710 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
28720 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
28730 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
28740 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
28750 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
28760 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
28770 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
28780 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
28790 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
287a0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
287b0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
287c0 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
287d0 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
287e0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
287f0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
28800 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
28810 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
28820 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
28830 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
28840 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
28850 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
28860 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
28870 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
28880 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
28890 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
288a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
288b0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
288c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
288d0 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
288e0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
288f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
28900 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
28910 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
28920 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
28930 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
28940 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
28950 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
28960 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
28970 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
28980 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
28990 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
289a0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
289b0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
289c0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
289d0 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
289e0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
289f0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
28a00 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
28a10 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
28a20 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
28a30 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
28a40 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
28a50 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
28a60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28a70 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
28a80 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
28a90 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
28aa0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
28ab0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
28ac0 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
28ad0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
28ae0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
28af0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
28b00 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
28b10 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
28b20 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
28b30 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
28b40 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
28b50 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
28b60 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
28b70 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
28b80 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
28b90 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d   Been Reset.** M
28ba0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
28bb0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
28bc0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
28bd0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
28be0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
28bf0 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
28c00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c10 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
28c20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
28c30 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
28c40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
28c50 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65  ] but has neithe
28c60 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  r run to complet
28c70 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a  ion (returned.**
28c80 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66   [SQLITE_DONE] f
28c90 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rom [sqlite3_ste
28ca0 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65  p(S)]) nor.** be
28cb0 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
28cc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
28cd0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
28ce0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
28cf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28d00 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
28d10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
28d20 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
28d30 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
28d40 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
28d50 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
28d60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28d70 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
28d80 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
28d90 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
28da0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
28db0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
28dc0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
28dd0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
28de0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
28df0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
28e00 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
28e10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28e20 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
28e30 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
28e40 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
28e50 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
28e60 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
28e70 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
28e80 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
28e90 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
28ea0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
28eb0 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
28ec0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
28ed0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
28ee0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
28ef0 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  pen..*/.int sqli
28f00 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
28f10 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
28f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28f30 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
28f40 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
28f50 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
28f60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28f70 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
28f80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
28f90 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
28fa0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
28fb0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
28fc0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
28fd0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
28fe0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
28ff0 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
29000 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
29010 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
29020 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
29030 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
29040 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
29050 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
29060 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
29070 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
29080 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
29090 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
290a0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
290b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
290c0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
290d0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
290e0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
290f0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
29100 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
29110 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29120 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
29130 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
29140 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
29150 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
29160 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29170 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
29180 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
29190 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
291a0 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
291b0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
291c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
291d0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
291e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
291f0 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ue.  The.** [sql
29200 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
29210 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ] interface can 
29220 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74  be used to const
29230 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70  ruct a new .** p
29240 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29250 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75  _value from an u
29260 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
29270 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
29280 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
29290 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
292a0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
292b0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
292c0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
292d0 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
292e0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
292f0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
29300 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29310 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
29320 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
29330 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
29340 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29350 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
29360 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
29370 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
29380 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
29390 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
293a0 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
293b0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
293c0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
293d0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
293e0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
293f0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
29400 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
29410 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
29420 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
29430 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
29440 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
29450 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
29460 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
29470 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
29480 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
29490 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
294a0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
294b0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
294c0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
294d0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
294e0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
294f0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
29500 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
29510 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
29520 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
29530 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
29540 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
29550 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29560 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
29570 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
29580 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
29590 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
295a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
295b0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
295c0 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
295d0 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
295e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
295f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29600 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
29610 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
29620 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
29630 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
29640 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
29650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
29660 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
29670 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
29680 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29690 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
296a0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
296b0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
296c0 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
296d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
296e0 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
296f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
29700 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
29710 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
29720 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
29730 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
29740 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29750 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
29760 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
29770 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
29780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29790 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
297a0 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
297b0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
297c0 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
297d0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
297e0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
297f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
29800 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
29810 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
29820 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
29830 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
29840 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
29850 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
29860 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29870 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
29880 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29890 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
298a0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
298b0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
298c0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
298d0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
298e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
298f0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
29900 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
29910 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29920 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
29930 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
29940 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
29950 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
29960 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
29970 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
29980 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
29990 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
299a0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
299b0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
299c0 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
299d0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
299e0 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
299f0 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
29a00 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
29a10 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
29a20 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
29a30 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
29a40 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
29a50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
29a60 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
29a70 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
29a80 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
29a90 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  g}.** METHOD: sq
29aa0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
29ab0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
29ac0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
29ad0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
29ae0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
29af0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
29b00 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
29b10 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
29b20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
29b30 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
29b40 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
29b50 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
29b60 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
29b70 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
29b80 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
29b90 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
29ba0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
29bb0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
29bc0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
29bd0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
29be0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
29bf0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
29c00 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
29c10 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
29c20 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
29c30 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
29c40 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
29c50 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
29c60 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
29c70 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
29c80 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
29c90 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
29ca0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29cb0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
29cc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
29cd0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
29ce0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29cf0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
29d00 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
29d10 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
29d20 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
29d30 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
29d40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29d50 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
29d60 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
29d70 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
29d80 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
29d90 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
29da0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
29db0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
29dc0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
29dd0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
29de0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
29df0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
29e00 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
29e10 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
29e20 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
29e30 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
29e40 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
29e50 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
29e60 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
29e70 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
29e80 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
29e90 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
29ea0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
29eb0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
29ec0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29ed0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
29ee0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
29ef0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
29f00 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
29f10 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
29f20 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
29f30 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
29f40 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
29f50 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
29f60 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
29f70 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
29f80 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
29f90 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
29fa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
29fb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
29fc0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
29fd0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
29fe0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
29ff0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2a000 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a010 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a020 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
2a030 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
2a040 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
2a050 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
2a060 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2a070 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
2a080 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
2a090 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
2a0a0 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
2a0b0 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
2a0c0 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
2a0d0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
2a0e0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
2a0f0 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
2a100 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2a110 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
2a120 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
2a130 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
2a140 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a150 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
2a160 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
2a170 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2a180 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
2a190 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2a1a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a1b0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2a1c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a1d0 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
2a1e0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2a1f0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
2a200 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
2a210 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
2a220 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2a230 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2a240 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
2a250 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a260 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a270 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
2a280 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
2a290 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2a2a0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
2a2b0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
2a2c0 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
2a2d0 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
2a2e0 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
2a2f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a300 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
2a310 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2a320 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
2a330 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2a340 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2a350 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2a360 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2a370 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2a380 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2a390 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2a3a0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2a3b0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2a3c0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2a3d0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2a3e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2a3f0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a400 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2a410 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2a420 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2a430 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2a440 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2a450 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2a460 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2a470 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2a480 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2a490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2a4a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a4b0 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
2a4c0 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
2a4d0 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
2a4e0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
2a4f0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2a500 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
2a510 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
2a520 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2a530 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
2a540 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
2a550 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2a560 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2a570 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2a580 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
2a590 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
2a5a0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2a5b0 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2a5c0 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2a5d0 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2a5e0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2a5f0 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2a600 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2a610 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2a620 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2a630 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2a640 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2a650 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2a660 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2a670 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2a680 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2a690 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2a6a0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2a6b0 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2a6c0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2a6d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a6e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2a6f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2a700 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2a710 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a720 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2a730 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2a740 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2a750 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2a760 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2a770 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2a780 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2a790 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2a7a0 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2a7b0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2a7c0 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2a7d0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2a7e0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2a7f0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2a800 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2a810 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2a820 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2a830 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2a840 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2a850 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2a860 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2a870 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2a880 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2a890 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2a8a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a8b0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2a8c0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2a8d0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2a8e0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2a8f0 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2a900 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2a910 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2a920 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2a930 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2a940 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2a950 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2a960 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2a970 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2a980 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2a990 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2a9a0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2a9b0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2a9c0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2a9d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2a9e0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2a9f0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2aa00 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2aa10 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2aa20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2aa30 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2aa40 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2aa50 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2aa60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2aa70 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2aa80 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2aa90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2aaa0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2aab0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2aac0 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2aad0 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2aae0 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2aaf0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2ab00 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2ab10 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2ab20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2ab30 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2ab40 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2ab50 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2ab60 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2ab70 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2ab80 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2ab90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2aba0 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2abb0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2abc0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2abd0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2abe0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2abf0 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2ac00 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2ac10 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2ac20 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2ac30 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2ac40 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2ac50 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2ac60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ac70 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2ac80 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ac90 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2aca0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2acb0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2acc0 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2acd0 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
2ace0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2acf0 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
2ad00 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2ad10 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
2ad20 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2ad30 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2ad40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2ad50 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2ad60 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2ad70 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2ad80 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2ad90 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2ada0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2adb0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2adc0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2add0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2ade0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2adf0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2ae00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ae10 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2ae20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ae30 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2ae40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2ae50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2ae60 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2ae70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2ae80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ae90 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2aea0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2aeb0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2aec0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2aed0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aee0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2aef0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2af00 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2af10 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2af20 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2af30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2af40 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2af50 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2af60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2af70 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2af80 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
2af90 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2afa0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2afb0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2afc0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
2afd0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2afe0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2aff0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2b000 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2b010 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2b020 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2b030 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2b040 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2b050 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2b060 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b070 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2b080 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2b090 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2b0a0 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2b0b0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2b0c0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2b0d0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2b0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2b0f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2b100 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2b110 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69  oding);.int sqli
2b120 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2b130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b140 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2b150 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2b160 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2b170 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2b180 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2b190 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b1a0 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
2b1b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b1c0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
2b1d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b1e0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2b1f0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
2b200 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2b210 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
2b220 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2b230 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2b240 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2b250 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2b260 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b270 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2b280 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2b290 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2b2a0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2b2b0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2b2c0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2b2d0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2b2e0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2b2f0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2b300 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2b310 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2b320 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2b330 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2b340 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2b350 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2b360 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2b370 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2b380 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2b390 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2b3a0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2b3b0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2b3c0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2b3d0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2b3e0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2b3f0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2b400 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2b410 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2b420 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2b430 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2b440 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b450 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2b460 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2b470 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b480 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2b490 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2b4a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b4b0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2b4c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b4d0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2b4e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b4f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b500 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2b510 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
2b520 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2b530 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2b540 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b550 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2b560 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2b570 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2b580 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2b590 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2b5a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b5b0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2b5c0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2b5d0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2b5e0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2b5f0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2b600 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2b610 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2b620 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2b630 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2b640 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2b650 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2b660 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2b670 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2b680 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2b690 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2b6a0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2b6b0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2b6c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2b6d0 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2b6e0 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2b6f0 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2b700 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2b710 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2b720 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2b730 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2b740 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2b750 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2b760 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2b770 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2b780 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2b790 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2b7a0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2b7b0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2b7c0 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2b7d0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2b7e0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2b7f0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2b800 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2b810 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2b820 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2b830 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2b840 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2b850 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2b860 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2b870 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b880 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2b890 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b8a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2b8b0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2b8c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b8d0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2b8e0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2b8f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b900 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2b910 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b920 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b930 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2b940 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2b950 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2b960 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2b970 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2b980 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2b990 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b9a0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2b9b0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2b9c0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2b9d0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2b9e0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2b9f0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2ba00 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2ba10 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2ba20 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2ba30 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2ba40 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2ba50 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2ba60 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2ba70 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2ba80 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2ba90 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2baa0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2bab0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2bac0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2bad0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2bae0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2baf0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2bb00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2bb10 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2bb20 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2bb30 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2bb40 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2bb50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bb60 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2bb70 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2bb80 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2bb90 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
2bba0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bbb0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2bbc0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2bbd0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2bbe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2bbf0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2bc00 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2bc10 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
2bc20 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2bc30 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
2bc40 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2bc50 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2bc60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2bc70 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2bc80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2bc90 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2bca0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2bcb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2bcc0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2bcd0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2bce0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2bcf0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
2bd00 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2bd10 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2bd20 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2bd30 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2bd40 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2bd50 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2bd60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2bd70 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2bd80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2bd90 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2bda0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2bdb0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2bdc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bdd0 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2bde0 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2bdf0 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2be00 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2be10 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2be20 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2be30 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2be40 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2be50 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2be60 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2be70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2be80 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2be90 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2bea0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2beb0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2bec0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2bed0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2bee0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2bef0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2bf00 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2bf10 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2bf20 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2bf30 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2bf40 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2bf50 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2bf60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2bf70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2bf80 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2bf90 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2bfa0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2bfb0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2bfc0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2bfd0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2bfe0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2bff0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2c000 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2c010 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2c020 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c030 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2c040 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2c050 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c060 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2c070 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c080 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2c090 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2c0a0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2c0b0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2c0c0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2c0d0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2c0e0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2c0f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c100 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2c110 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2c120 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c130 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2c140 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2c150 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2c160 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2c170 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2c180 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2c190 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2c1a0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2c1b0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2c1c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c1d0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2c1e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2c1f0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2c200 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2c210 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2c220 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2c230 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2c240 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2c250 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2c260 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2c270 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2c280 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2c290 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2c2a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2c2b0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2c2c0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2c2d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2c2e0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2c2f0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2c300 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2c310 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2c320 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2c330 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2c340 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c350 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2c360 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2c370 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2c380 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2c390 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2c3a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2c3b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c3c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c3d0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
2c3e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c3f0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2c400 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2c410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c420 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2c430 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2c440 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
2c450 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c460 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c470 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2c480 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2c490 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2c4a0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2c4b0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2c4c0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2c4d0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2c4e0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2c4f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c500 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2c510 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2c520 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2c530 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2c540 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2c550 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2c560 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2c570 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2c580 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2c590 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2c5a0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2c5b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2c5c0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2c5d0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2c5e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c5f0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2c600 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2c610 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2c620 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2c630 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c640 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2c650 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2c660 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2c670 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2c680 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2c690 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2c6a0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2c6b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c6c0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2c6d0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2c6e0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2c6f0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2c700 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2c710 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2c720 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2c730 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2c740 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2c750 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2c760 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2c770 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2c780 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2c790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2c7a0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2c7b0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2c7c0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2c7d0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2c7e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2c7f0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2c800 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2c810 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2c820 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2c830 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2c840 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2c850 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2c860 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2c870 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2c880 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2c890 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2c8a0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2c8b0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2c8c0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2c8d0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2c8e0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2c8f0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2c900 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2c910 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2c920 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2c930 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2c940 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2c950 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2c960 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2c970 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2c980 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2c990 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2c9a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2c9b0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2c9c0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2c9d0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2c9e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2c9f0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2ca00 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2ca10 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2ca20 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2ca30 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2ca40 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2ca50 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2ca60 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2ca70 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2ca80 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2ca90 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2caa0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2cab0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2cac0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2cad0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2cae0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2caf0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2cb00 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2cb10 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2cb20 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2cb30 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2cb40 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2cb50 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2cb60 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2cb70 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2cb80 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2cb90 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2cba0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2cbb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2cbc0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2cbd0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2cbe0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2cbf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2cc00 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2cc10 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2cc20 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2cc30 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2cc40 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2cc50 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2cc60 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2cc70 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2cc80 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2cc90 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2cca0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ccb0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
2ccc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2ccd0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2cce0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2ccf0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2cd00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2cd10 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2cd20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2cd30 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2cd40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2cd50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2cd60 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2cd70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2cd80 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2cd90 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2cda0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2cdb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2cdc0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2cdd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2cde0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2cdf0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2ce00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ce10 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2ce20 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2ce30 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2ce40 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ce50 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2ce60 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2ce70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ce80 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2ce90 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2cea0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2ceb0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2cec0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2ced0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2cee0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2cef0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2cf00 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2cf10 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2cf20 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2cf30 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2cf40 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2cf50 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2cf60 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2cf70 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2cf80 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2cf90 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2cfa0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2cfb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2cfc0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2cfd0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2cfe0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2cff0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2d000 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2d010 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2d020 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2d030 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2d040 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2d050 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2d060 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2d070 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2d080 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2d090 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2d0a0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2d0b0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2d0c0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2d0d0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2d0e0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2d0f0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2d100 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2d110 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2d120 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2d130 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2d140 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2d150 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2d160 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2d170 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2d180 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2d190 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2d1a0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2d1b0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2d1c0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2d1d0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2d1e0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2d1f0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2d200 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2d210 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2d220 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2d230 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2d240 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2d250 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2d260 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2d270 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2d280 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2d290 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2d2a0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
2d2b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2d2c0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2d2d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2d2e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d2f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2d300 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2d310 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2d320 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2d330 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2d340 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2d350 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d360 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2d370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2d380 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2d390 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2d3a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d3b0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2d3c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d3d0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2d3e0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2d3f0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2d400 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2d410 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d420 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2d430 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2d440 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2d450 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2d460 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2d470 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2d480 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2d490 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2d4a0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2d4b0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2d4c0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2d4d0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2d4e0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2d4f0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2d500 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2d510 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2d520 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d530 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2d540 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2d550 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2d560 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2d570 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2d580 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2d590 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2d5a0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2d5b0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2d5c0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2d5d0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2d5e0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2d5f0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2d600 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2d610 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2d620 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2d630 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2d640 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2d650 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2d660 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2d670 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2d680 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2d690 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d6a0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2d6b0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2d6c0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2d6d0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
2d6e0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
2d6f0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
2d700 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
2d710 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
2d720 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
2d730 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
2d740 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2d750 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2d760 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2d770 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2d780 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2d790 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2d7a0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2d7b0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2d7c0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2d7d0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2d7e0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2d7f0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2d800 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2d810 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2d820 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2d830 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2d840 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2d850 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2d860 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2d870 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2d880 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2d890 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2d8a0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2d8b0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2d8c0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2d8d0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2d8e0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2d8f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2d900 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2d910 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2d920 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2d930 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2d940 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2d950 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2d960 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2d970 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2d980 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2d990 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2d9a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2d9b0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2d9c0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2d9d0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2d9e0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2d9f0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2da00 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2da10 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2da20 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2da30 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2da40 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2da50 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2da60 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2da70 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2da80 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2da90 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2daa0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2dab0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2dac0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2dad0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2dae0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2daf0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2db00 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2db10 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2db20 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2db30 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2db40 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2db50 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2db60 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2db70 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2db80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2db90 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2dba0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2dbb0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2dbc0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2dbd0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2dbe0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2dbf0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2dc00 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2dc10 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2dc20 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2dc30 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2dc40 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2dc50 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2dc60 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2dc70 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2dc80 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2dc90 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2dca0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2dcb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2dcc0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2dcd0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2dce0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2dcf0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2dd00 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2dd10 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2dd20 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2dd30 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2dd40 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2dd50 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2dd60 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2dd70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2dd80 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2dd90 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2dda0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2ddb0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2ddc0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2ddd0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2dde0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2ddf0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2de00 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2de10 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2de20 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2de30 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2de40 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2de50 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2de60 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2de70 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2de80 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2de90 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2dea0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2deb0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2dec0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2ded0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2dee0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2def0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2df00 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2df10 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2df20 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2df30 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2df40 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2df50 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2df60 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2df70 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2df80 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2df90 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2dfa0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2dfb0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2dfc0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2dfd0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2dfe0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2dff0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2e000 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2e010 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2e020 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2e030 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2e040 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2e050 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2e060 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2e070 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2e080 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2e090 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2e0a0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2e0b0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2e0c0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2e0d0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2e0e0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2e0f0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2e100 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2e110 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2e120 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2e130 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2e140 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2e150 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2e160 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2e170 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2e180 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2e190 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2e1a0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2e1b0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2e1c0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2e1d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2e1e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2e1f0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2e200 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2e210 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2e220 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2e230 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2e240 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2e250 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e260 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2e270 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2e280 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2e290 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2e2a0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2e2b0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2e2c0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2e2d0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2e2e0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2e2f0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2e300 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2e310 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2e320 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2e330 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2e340 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2e350 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2e360 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2e370 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e380 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2e390 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2e3a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e3b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2e3c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2e3d0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2e3e0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2e3f0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2e400 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2e410 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2e420 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2e430 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2e440 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2e450 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2e460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
2e470 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2e480 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e490 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2e4a0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2e4b0 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
2e4c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e4d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e4e0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
2e4f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e500 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2e510 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
2e520 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2e530 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2e540 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e550 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
2e560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e570 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
2e580 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
2e590 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
2e5a0 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
2e5b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e5c0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
2e5d0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
2e5e0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
2e5f0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2e600 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
2e610 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2e620 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2e630 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
2e640 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
2e650 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2e660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2e670 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2e680 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2e690 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
2e6a0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e6b0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2e6c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
2e6d0 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
2e6e0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
2e6f0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
2e700 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
2e710 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
2e720 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2e730 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2e740 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
2e750 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
2e760 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
2e770 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
2e780 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
2e790 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
2e7a0 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
2e7b0 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
2e7c0 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
2e7d0 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
2e7e0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
2e7f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2e800 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2e810 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
2e820 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2e830 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2e840 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e850 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2e860 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2e870 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2e880 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2e890 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2e8a0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2e8b0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2e8c0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2e8d0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2e8e0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2e8f0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2e900 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2e910 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2e920 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2e930 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2e940 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2e950 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2e960 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2e970 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2e980 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2e990 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2e9a0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2e9b0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2e9c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2e9d0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2e9e0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2e9f0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2ea00 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2ea10 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2ea20 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2ea30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2ea40 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2ea50 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2ea60 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2ea70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ea80 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2ea90 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2eaa0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2eab0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2eac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2ead0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2eae0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2eaf0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2eb00 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2eb10 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2eb20 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2eb30 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2eb40 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2eb50 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2eb60 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2eb70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2eb80 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2eb90 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
2eba0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ebb0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2ebc0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2ebd0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2ebe0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2ebf0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2ec00 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2ec10 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2ec20 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2ec30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2ec40 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2ec50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ec60 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2ec70 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2ec80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2ec90 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2eca0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2ecb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ecc0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2ecd0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2ece0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2ecf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2ed00 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2ed10 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2ed20 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2ed30 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2ed40 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2ed50 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2ed60 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2ed70 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2ed80 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2ed90 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2eda0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2edb0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2edc0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2edd0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2ede0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2edf0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2ee00 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2ee10 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2ee20 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2ee30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2ee40 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2ee50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2ee60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2ee70 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2ee80 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2ee90 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2eea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2eeb0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2eec0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2eed0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2eee0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2eef0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ef00 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2ef10 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2ef20 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2ef30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ef40 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2ef50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ef60 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2ef70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2ef80 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2ef90 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2efa0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2efb0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2efc0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2efd0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2efe0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2eff0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2f000 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f010 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2f020 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2f030 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2f040 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2f050 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2f060 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2f070 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2f080 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2f090 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f0a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2f0b0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2f0c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2f0d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2f0e0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2f0f0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2f100 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2f110 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2f120 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2f130 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2f140 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2f150 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2f160 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2f170 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2f180 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2f190 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2f1a0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2f1b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f1c0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2f1d0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2f1e0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2f1f0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2f200 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2f210 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2f220 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2f230 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2f240 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2f250 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f260 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2f270 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2f280 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2f290 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2f2a0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2f2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2f2c0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2f2d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2f2e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2f2f0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2f300 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2f310 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2f320 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2f330 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2f340 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f350 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2f360 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2f370 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f380 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2f390 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2f3a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f3b0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2f3c0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2f3d0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2f3e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f3f0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2f400 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2f410 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2f420 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f430 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2f440 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2f450 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2f460 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2f470 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2f480 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2f490 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f4a0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2f4b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f4c0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2f4d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f4e0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2f4f0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2f500 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2f510 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2f520 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2f530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f540 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2f550 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2f560 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2f570 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2f580 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2f590 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2f5a0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2f5b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f5c0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2f5d0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2f5e0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2f5f0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2f600 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2f610 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f620 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2f630 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2f640 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f650 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2f660 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2f670 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2f680 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2f690 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2f6a0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2f6b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2f6c0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2f6d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f6e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2f6f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f700 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2f710 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2f720 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2f730 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f740 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2f750 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f760 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2f770 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2f780 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2f790 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2f7a0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2f7b0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2f7c0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2f7d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2f7e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2f7f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2f800 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2f810 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2f820 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2f830 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2f840 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2f850 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2f860 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2f870 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f880 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2f890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f8a0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2f8b0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2f8c0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2f8d0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2f8e0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2f8f0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2f900 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2f910 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2f920 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2f930 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
2f940 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
2f950 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2f960 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f970 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2f980 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2f990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f9a0 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
2f9b0 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
2f9c0 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
2f9d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2f9e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2f9f0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2fa00 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
2fa10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2fa20 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2fa30 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2fa40 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2fa50 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2fa60 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2fa70 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2fa80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2fa90 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2faa0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2fab0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2fac0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2fad0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2fae0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2faf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fb00 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2fb10 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2fb20 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
2fb30 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
2fb40 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  afe..**.** These
2fb50 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2fb60 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2fb70 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2fb80 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2fb90 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2fba0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2fbb0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2fbc0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2fbd0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2fbe0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2fbf0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2fc00 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2fc10 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2fc20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2fc30 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2fc40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2fc50 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2fc60 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2fc70 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2fc80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2fc90 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2fca0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2fcb0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2fcc0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2fcd0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2fce0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2fcf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2fd00 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2fd10 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2fd20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2fd30 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2fd40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2fd50 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2fd60 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2fd70 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2fd80 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
2fd90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2fda0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2fdb0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2fdc0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2fdd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2fde0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2fdf0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
2fe00 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2fe10 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
2fe20 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2fe30 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2fe40 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2fe50 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2fe60 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
2fe70 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2fe80 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
2fe90 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2fea0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
2feb0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2fec0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2fed0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2fee0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2fef0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2ff00 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2ff10 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2ff20 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
2ff30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2ff40 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
2ff50 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2ff60 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
2ff70 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2ff80 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2ff90 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
2ffa0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
2ffb0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
2ffc0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
2ffd0 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
2ffe0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2fff0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
30000 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
30010 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
30020 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30030 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30040 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
30050 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
30060 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
30070 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
30080 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
30090 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
300a0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
300b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
300c0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
300d0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
300e0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  uote>)^.**.** No
300f0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
30100 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
30110 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
30120 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
30130 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
30140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30150 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
30160 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
30170 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
30180 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
30190 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
301a0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
301b0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
301c0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
301d0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
301e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
301f0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
30200 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
30210 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
30220 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
30230 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30240 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30250 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30260 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
30270 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
30280 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
30290 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
302a0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
302b0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
302c0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
302d0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
302e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
302f0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
30300 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
30310 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
30320 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
30330 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
30340 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
30350 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
30360 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
30370 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
30380 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
30390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
303a0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
303b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
303c0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
303d0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
303e0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
303f0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
30400 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
30410 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
30420 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
30430 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
30440 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
30450 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
30460 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
30470 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
30480 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
30490 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
304a0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
304b0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
304c0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
304d0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
304e0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
304f0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
30500 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
30510 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
30520 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
30530 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
30540 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
30550 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
30560 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
30570 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
30580 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
30590 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f  ** The safest po
305a0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
305b0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
305c0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
305d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
305e0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
305f0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
30600 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
30610 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
30620 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
30630 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
30640 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30650 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
30660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30670 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
30680 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
30690 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
306a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
306b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
306c0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
306d0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
306e0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
306f0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
30700 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
30710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30720 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
30730 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
30740 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
30750 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
30760 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
30770 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
30780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30790 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
307a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
307b0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
307c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
307d0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
307e0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
307f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30800 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
30810 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
30820 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
30830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30840 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
30850 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
30860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30870 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
30880 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
30890 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
308a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
308b0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
308c0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
308d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
308e0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
308f0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
30900 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
30910 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
30920 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
30930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
30940 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
30950 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
30960 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
30970 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
30980 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
30990 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
309a0 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e   Do <em>not</em>
309b0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
309c0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
309d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
309e0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
309f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30a00 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
30a10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
30a20 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
30a30 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
30a40 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
30a50 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
30a60 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
30a70 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
30a80 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
30a90 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
30aa0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
30ab0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
30ac0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
30ad0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
30ae0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
30af0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
30b00 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
30b10 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
30b20 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
30b30 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
30b40 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
30b50 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
30b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
30b70 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
30b80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
30b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30ba0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
30bb0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
30bc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
30bd0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
30be0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30bf0 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
30c00 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
30c10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30c20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
30c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
30c40 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30c50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
30c60 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
30c70 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
30c80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30c90 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
30ca0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
30cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30cc0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30cd0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
30ce0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30cf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
30d00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30d10 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
30d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
30d30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30d40 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
30d50 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
30d60 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
30d70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30d80 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
30d90 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
30da0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
30db0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
30dc0 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
30dd0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30de0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
30df0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
30e00 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
30e10 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
30e20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
30e30 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
30e40 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
30e50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
30e60 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
30e70 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
30e80 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
30e90 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
30ea0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
30eb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
30ec0 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
30ed0 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
30ee0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
30ef0 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
30f00 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
30f10 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
30f20 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
30f30 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
30f40 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
30f50 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
30f60 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
30f70 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
30f80 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
30f90 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
30fa0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
30fb0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
30fc0 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
30fd0 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
30fe0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
30ff0 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
31000 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
31010 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
31020 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
31030 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
31040 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
31050 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31060 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
31070 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
31080 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
31090 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
310a0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
310b0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
310c0 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
310d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
310e0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
310f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
31100 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
31110 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
31120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31130 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
31140 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
31150 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
31160 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
31170 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
31180 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
31190 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
311a0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
311b0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
311c0 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
311d0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
311e0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
311f0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
31200 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
31210 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
31220 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
31230 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
31240 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
31250 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
31260 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
31270 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
31280 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
312a0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
312b0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
312c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
312d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
312e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
312f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
31300 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
31310 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31320 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
31330 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
31340 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
31350 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
31360 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
31370 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
31380 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
31390 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
313a0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
313b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
313c0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
313d0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
313e0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
313f0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
31400 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
31410 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
31420 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
31430 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
31440 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
31450 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
31460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31470 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
31480 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
31490 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
314a0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
314b0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
314c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
314d0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
314e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
314f0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
31500 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
31510 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
31520 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
31530 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
31540 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
31550 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
31560 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
31570 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
31580 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
31590 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
315a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
315b0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
315c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
315d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
315e0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
315f0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
31600 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
31610 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
31620 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
31630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
31640 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
31650 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
31660 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
31670 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
31680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31690 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
316a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
316b0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
316c0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
316d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
316e0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
316f0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
31700 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
31710 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
31720 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
31730 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
31740 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
31750 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31760 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
31770 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
31780 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31790 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
317a0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
317b0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
317c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
317d0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
317e0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
317f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
31800 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
31810 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
31820 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
31830 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
31840 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
31850 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
31860 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
31870 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
31880 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
31890 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
318a0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
318b0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
318c0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
318d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
318e0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
318f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
31900 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
31910 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
31920 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
31930 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
31940 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
31950 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
31960 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
31970 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31980 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
31990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
319a0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
319b0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
319c0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
319d0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
319e0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
319f0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
31a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
31a10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31a20 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
31a30 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
31a40 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
31a50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31a60 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
31a70 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
31a80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
31a90 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
31aa0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
31ab0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
31ac0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
31ad0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
31ae0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
31af0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
31b00 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
31b10 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
31b20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
31b30 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
31b40 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
31b50 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
31b60 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
31b70 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
31b80 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
31b90 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
31ba0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
31bb0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
31bc0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
31bd0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
31be0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
31bf0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
31c00 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
31c10 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
31c20 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
31c30 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
31c40 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
31c50 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
31c60 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
31c70 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
31c80 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
31c90 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
31ca0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
31cb0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
31cc0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
31cd0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
31ce0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
31cf0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
31d00 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
31d10 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
31d20 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
31d30 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
31d40 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
31d50 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
31d60 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
31d70 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
31d80 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
31d90 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
31da0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
31db0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
31dc0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
31dd0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
31de0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
31df0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
31e00 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
31e10 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
31e20 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
31e30 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
31e40 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
31e50 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
31e60 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
31e70 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
31e80 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
31e90 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
31ea0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
31eb0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
31ec0 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
31ed0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31ee0 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
31ef0 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
31f00 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
31f10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31f20 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
31f30 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
31f40 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
31f50 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
31f60 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
31f70 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
31f80 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
31f90 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
31fa0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
31fb0 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
31fc0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
31fd0 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
31fe0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
31ff0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
32000 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32010 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
32020 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
32030 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
32040 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
32050 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
32060 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
32070 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
32080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
32090 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
320a0 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
320b0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
320c0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
320d0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
320e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
320f0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
32100 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
32110 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
32120 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
32130 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
32140 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
32150 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
32160 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
32170 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
32180 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
32190 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
321a0 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
321b0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
321c0 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
321d0 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
321e0 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
321f0 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
32200 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
32210 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
32220 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
32230 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
32240 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
32250 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
32260 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
32270 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
32280 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
32290 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
322a0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
322b0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
322c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
322d0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
322e0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
322f0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
32300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
32310 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
32320 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
32330 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
32340 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
32350 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
32360 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
32370 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
32380 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
32390 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
323a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
323b0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
323c0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
323d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
323e0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
323f0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
32400 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
32410 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
32420 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
32430 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
32440 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
32450 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
32460 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
32470 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
32480 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32490 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
324a0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
324b0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
324c0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
324d0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
324e0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
324f0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
32500 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
32510 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
32520 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
32530 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
32540 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
32550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32560 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32570 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
32580 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
32590 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
325a0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
325b0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
325c0 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
325d0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
325e0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
325f0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
32600 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
32610 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
32620 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
32630 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
32640 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
32650 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
32660 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
32670 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
32680 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32690 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
326a0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
326b0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
326c0 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
326d0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
326e0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
326f0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
32700 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
32710 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
32720 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
32730 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
32740 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
32750 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
32760 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32770 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
32780 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
32790 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
327a0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
327b0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
327c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
327d0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
327e0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
327f0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
32800 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
32810 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
32820 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
32830 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
32840 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
32850 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32860 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
32870 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
32880 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
32890 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
328a0 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
328b0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
328c0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
328d0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
328e0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
328f0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
32900 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
32910 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
32920 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
32930 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
32940 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
32950 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
32960 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
32970 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
32980 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
32990 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
329a0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
329b0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
329c0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
329d0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
329e0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
329f0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
32a00 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
32a10 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
32a20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
32a30 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
32a40 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
32a50 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
32a60 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
32a70 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
32a80 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
32a90 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
32aa0 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
32ab0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32ac0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
32ad0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
32ae0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32af0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
32b00 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
32b10 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
32b20 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
32b30 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
32b40 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
32b50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32b60 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
32b70 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
32b80 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
32b90 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
32ba0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32bb0 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
32bc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32bd0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
32be0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
32bf0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
32c00 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
32c10 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
32c20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
32c30 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
32c40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
32c50 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
32c60 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
32c70 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
32c80 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32c90 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32ca0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
32cb0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
32cc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32cd0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
32ce0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
32cf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
32d00 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
32d10 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
32d20 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
32d30 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
32d40 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
32d50 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
32d60 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
32d70 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
32d80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
32d90 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
32da0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
32db0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
32dc0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
32dd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32de0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
32df0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
32e00 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
32e10 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
32e20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32e30 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
32e40 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
32e50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32e60 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32e70 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32e80 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
32e90 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32ea0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32eb0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
32ec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
32ed0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
32ee0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
32ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
32f00 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
32f10 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
32f20 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
32f30 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
32f40 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
32f50 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
32f60 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
32f70 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
32f80 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
32f90 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f            1    /
32fa0 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33  * IMP: R-37514-3
32fb0 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20  5566 */.#define 
32fc0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
32fd0 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d        2    /* IM
32fe0 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37  P: R-03371-37637
32ff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
33000 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
33010 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    3    /* IMP: R
33020 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a  -51971-34154 */.
33030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
33040 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
33050 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
33060 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
33070 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
33080 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
33090 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
330a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
330b0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
330c0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
330d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
330e0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
330f0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
33100 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
33110 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
33120 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
33130 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
33140 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
33150 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
33160 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
33170 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
33180 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
33190 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
331a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
331b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
331c0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
331d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
331e0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
331f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
33200 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
33210 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
33220 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
33230 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
33240 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
33250 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
33260 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
33270 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
33280 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
33290 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
332a0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
332b0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
332c0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
332d0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
332e0 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
332f0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
33300 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
33310 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
33320 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61  ons.  To encoura
33330 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74  ge programmers t
33340 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65  o avoid.** these
33350 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77   functions, we w
33360 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20  ill not explain 
33370 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
33380 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
33390 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
333a0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
333b0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
333c0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
333d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
333e0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
333f0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
33400 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
33410 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
33420 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
33430 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
33440 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
33450 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
33460 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
33470 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
33480 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
33490 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
334a0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
334b0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
334c0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
334d0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
334e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
334f0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
33500 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
33510 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
33520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33530 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
33540 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
33550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33560 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61  Obtaining SQL Va
33570 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
33580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
33590 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
335a0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
335b0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
335c0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
335d0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
335e0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
335f0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
33600 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
33610 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
33620 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
33630 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a  gregate.  .**.**
33640 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
33650 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
33660 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
33670 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
33680 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
33690 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
336a0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
336b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
336c0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
336d0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
336e0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
336f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
33700 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
33710 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
33720 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
33730 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
33740 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
33750 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
33760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33770 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
33780 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
33790 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
337a0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
337b0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
337c0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
337d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
337e0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
337f0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
33800 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33810 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
33820 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
33830 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
33840 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33850 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
33860 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
33870 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
33880 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
33890 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
338a0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
338b0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
338c0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
338d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
338e0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
338f0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
33900 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
33910 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
33920 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
33930 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
33940 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
33950 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33960 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
33970 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
33980 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
33990 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
339a0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
339b0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
339c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
339d0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
339e0 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
339f0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
33a00 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
33a10 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
33a20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
33a30 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
33a40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
33a50 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
33a60 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
33a70 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
33a80 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
33a90 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
33aa0 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
33ab0 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
33ac0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
33ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
33ae0 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
33af0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
33b00 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
33b10 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
33b20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
33b30 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
33b40 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
33b50 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
33b60 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
33b70 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
33b80 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
33b90 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
33ba0 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
33bb0 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
33bc0 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
33bd0 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
33be0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
33bf0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
33c00 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
33c10 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
33c20 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
33c30 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
33c40 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
33c50 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
33c60 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
33c70 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
33c80 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
33c90 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
33ca0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
33cb0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
33cc0 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
33cd0 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
33ce0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
33cf0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
33d00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
33d10 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
33d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
33d30 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
33d40 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
33d50 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
33d60 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
33d70 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
33d80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
33d90 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
33da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33db0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
33dc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33dd0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
33de0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
33df0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
33e00 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
33e10 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
33e20 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
33e30 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
33e40 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
33e50 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
33e60 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
33e70 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
33e80 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
33e90 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
33ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33eb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33ec0 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
33ed0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
33ee0 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
33ef0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
33f00 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33f10 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
33f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33f30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
33f40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
33f50 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
33f60 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
33f70 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
33f80 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
33f90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
33fa0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33fb0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
33fc0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
33fd0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33fe0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
33ff0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34000 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
34010 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34020 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
34030 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
34040 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
34050 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
34060 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
34070 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
34080 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
34090 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
340a0 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
340b0 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
340c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
340d0 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
340e0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
340f0 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
34100 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
34110 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
34120 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
34130 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
34140 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
34150 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
34160 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
34170 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
34180 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
34190 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
341a0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
341b0 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
341c0 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
341d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
341e0 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
341f0 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
34200 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
34210 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
34220 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
34230 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
34240 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
34250 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
34260 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
34270 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
34280 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
34290 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
342a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
342b0 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
342c0 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
342d0 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64  her..*/.unsigned
342e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
342f0 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74  ue_subtype(sqlit
34300 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
34310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70  ** CAPI3REF: Cop
34320 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56  y And Free SQL V
34330 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
34340 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
34350 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34360 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
34370 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
34380 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
34390 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
343a0 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74  object D and ret
343b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
343c0 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54  o that copy.  ^T
343d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
343e0 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  e] returned.** i
343f0 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  s a [protected s
34400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34410 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65  ject even if the
34420 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a   input is not..*
34430 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
34440 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65  alue_dup(V) inte
34450 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
34460 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20  LL if V is NULL 
34470 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72  or if a.** memor
34480 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
34490 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ls..**.** ^The s
344a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
344b0 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66  e(V) interface f
344c0 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  rees an [sqlite3
344d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
344e0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
344f0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
34500 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
34510 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55  .  ^If V is a NU
34520 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  LL pointer.** th
34530 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  en sqlite3_value
34540 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61  _free(V) is a ha
34550 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
34560 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
34570 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  NTAL sqlite3_val
34580 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ue *sqlite3_valu
34590 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
345a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
345b0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
345c0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61   void sqlite3_va
345d0 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
345e0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
345f0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
34600 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
34610 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
34620 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
34630 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
34640 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
34650 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
34660 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
34670 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
34680 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
34690 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
346a0 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
346b0 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
346c0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
346d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
346e0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
346f0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
34700 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
34710 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
34720 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
34730 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
34740 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
34750 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
34760 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
34770 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
34780 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
34790 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
347a0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
347b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
347c0 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
347d0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
347e0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
347f0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
34800 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
34810 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34820 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
34830 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
34840 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
34850 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
34860 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
34870 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
34880 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
34890 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
348a0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
348b0 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
348c0 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
348d0 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
348e0 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
348f0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
34900 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
34910 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
34920 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
34930 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
34940 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
34950 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
34960 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
34970 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
34980 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
34990 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
349a0 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
349b0 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
349c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
349d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
349e0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
349f0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
34a00 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
34a10 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
34a20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
34a30 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
34a40 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
34a50 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
34a60 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
34a70 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
34a80 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
34a90 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
34aa0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
34ab0 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
34ac0 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
34ad0 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
34ae0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
34af0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
34b00 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
34b10 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
34b20 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
34b30 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
34b40 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
34b50 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
34b60 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
34b70 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
34b80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
34b90 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
34ba0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
34bb0 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
34bc0 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
34bd0 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
34be0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34bf0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
34c00 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
34c10 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
34c20 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
34c30 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
34c40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
34c50 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
34c60 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
34c70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34c80 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
34c90 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
34ca0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
34cb0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
34cc0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
34cd0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
34ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
34cf0 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
34d00 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
34d10 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
34d20 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
34d30 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
34d40 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
34d50 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
34d60 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
34d70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
34d80 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34d90 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
34da0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
34db0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
34dc0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
34dd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
34de0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
34df0 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
34e00 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
34e10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
34e20 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
34e30 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
34e40 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
34e50 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
34e60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
34e70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34e80 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
34e90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34ea0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
34eb0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
34ec0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
34ed0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
34ee0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
34ef0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34f00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34f10 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
34f20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34f30 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
34f40 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
34f50 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
34f60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
34f70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
34f80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34f90 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
34fa0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34fb0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
34fc0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
34fd0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34fe0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
34ff0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
35000 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
35010 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
35020 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35030 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
35040 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
35050 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
35060 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
35070 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35080 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
35090 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
350a0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
350b0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
350c0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
350d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
350e0 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
350f0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
35100 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35110 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
35120 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35130 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
35140 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
35150 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
35160 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
35170 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
35180 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
35190 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
351a0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
351b0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
351c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
351d0 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
351e0 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Data.** METHOD:
351f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
35200 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
35210 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
35220 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
35230 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
35240 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
35250 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
35260 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
35270 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
35280 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
35290 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
352a0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
352b0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
352c0 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
352d0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
352e0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
352f0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
35300 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
35310 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
35320 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
35330 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
35340 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
35350 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
35360 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
35370 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
35380 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
35390 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
353a0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
353b0 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
353c0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
353d0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
353e0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
353f0 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
35400 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
35410 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
35420 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
35430 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
35440 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
35450 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
35460 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
35470 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
35480 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
35490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
354a0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
354b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
354c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
354d0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
354e0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
354f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35500 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
35510 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
35520 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
35530 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35540 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
35550 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
35560 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
35570 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
35580 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
35590 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
355a0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
355b0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
355c0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
355d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
355e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
355f0 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
35600 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
35610 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
35620 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
35630 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
35640 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35650 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
35660 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
35670 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
35680 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
35690 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
356a0 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
356b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
356c0 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
356d0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
356e0 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
356f0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
35700 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
35710 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
35720 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
35730 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35740 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
35750 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
35760 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
35770 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
35780 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
35790 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
357a0 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
357b0 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
357c0 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
357d0 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
357e0 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
357f0 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
35800 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
35810 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
35820 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
35830 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
35840 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
35850 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
35860 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
35870 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
35880 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
35890 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
358a0 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
358b0 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
358c0 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
358d0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
358e0 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
358f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
35900 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
35910 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
35920 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
35930 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
35940 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
35950 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
35960 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
35970 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
35980 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
35990 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
359a0 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
359b0 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
359c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
359d0 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
359e0 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
359f0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
35a00 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
35a10 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
35a20 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
35a30 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
35a40 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
35a50 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
35a60 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
35a70 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35a80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35a90 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
35aa0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35ab0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
35ac0 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
35ad0 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
35ae0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
35af0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
35b00 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
35b10 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
35b20 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
35b30 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
35b40 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
35b50 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
35b60 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
35b70 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
35b80 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
35b90 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
35ba0 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
35bb0 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
35bc0 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
35bd0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
35be0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
35bf0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
35c00 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
35c10 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
35c20 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
35c30 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
35c40 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
35c50 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
35c60 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
35c70 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
35c80 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
35c90 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
35ca0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
35cb0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
35cc0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
35cd0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
35ce0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
35cf0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
35d00 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
35d10 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
35d20 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
35d30 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
35d40 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
35d50 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
35d60 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
35d70 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
35d80 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
35d90 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
35da0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
35db0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
35dc0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
35dd0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
35de0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
35df0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
35e00 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
35e10 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
35e20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
35e30 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
35e40 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
35e50 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
35e60 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
35e70 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
35e80 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
35e90 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
35ea0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
35eb0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
35ec0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
35ed0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
35ee0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
35ef0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
35f00 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
35f10 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
35f20 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
35f30 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
35f40 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
35f50 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
35f60 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
35f70 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
35f80 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
35f90 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
35fa0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
35fb0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
35fc0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
35fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
35fe0 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
35ff0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
36000 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  n.** METHOD: sql
36010 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
36020 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
36030 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
36040 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
36050 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
36060 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
36070 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
36080 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
36090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
360a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
360b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
360c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
360d0 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
360e0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
360f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
36100 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
36110 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
36120 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
36130 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
36140 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
36150 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
36160 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
36170 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
36180 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
36190 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
361a0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
361b0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
361c0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
361d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
361e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
361f0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
36200 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
36210 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
36220 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36230 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
36240 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
36250 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
36260 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
36270 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
36280 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
36290 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
362a0 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
362b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
362c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
362d0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
362e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
362f0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43  ult_zeroblob64(C
36300 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ,N).** interface
36310 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
36320 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
36330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36340 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
36350 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
36360 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61  all zero bytes a
36370 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
36380 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ze..**.** ^The s
36390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
363a0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
363b0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
363c0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
363d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
363e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
363f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
36400 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
36410 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
36420 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
36430 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36440 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
36450 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36460 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
36470 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
36480 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
36490 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
364a0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
364b0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
364c0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
364d0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
364e0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
364f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36500 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
36510 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
36520 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
36530 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
36540 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
36550 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
36560 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
36570 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
36580 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36590 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
365a0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
365b0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
365c0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
365d0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
365e0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
365f0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
36600 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
36610 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
36620 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
36630 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
36640 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
36650 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
36660 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
36670 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
36680 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
36690 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
366a0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
366b0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
366c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
366d0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
366e0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
366f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36700 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
36710 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
36720 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
36730 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
36740 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
36750 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
36760 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
36770 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
36780 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36790 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
367a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
367b0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
367c0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
367d0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
367e0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
367f0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
36800 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
36810 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
36820 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
36830 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
36840 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
36850 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
36860 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
36870 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36880 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
36890 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
368a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
368b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
368c0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
368d0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
368e0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
368f0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
36900 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
36910 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
36920 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
36930 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
36940 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
36950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36960 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
36970 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
36980 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
36990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
369a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
369b0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
369c0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
369d0 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
369e0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
369f0 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
36a00 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
36a10 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
36a20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36a30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36a40 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
36a50 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
36a60 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
36a70 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
36a80 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
36a90 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
36aa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36ab0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
36ac0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
36ad0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
36ae0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
36af0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36b00 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
36b10 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
36b20 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
36b30 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
36b40 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
36b50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36b60 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
36b70 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
36b80 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
36b90 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
36ba0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36bb0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
36bc0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
36bd0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
36be0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
36bf0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
36c00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36c10 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
36c20 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
36c30 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
36c40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36c50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36c60 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
36c70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36c80 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
36c90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36ca0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
36cb0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
36cc0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
36cd0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
36ce0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
36cf0 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
36d00 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
36d10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36d20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
36d30 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
36d40 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
36d50 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
36d60 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
36d70 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
36d80 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
36d90 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
36da0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
36db0 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  vely..** ^The sq
36dc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36dd0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
36de0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
36df0 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61  value of an.** a
36e00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36e10 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36e20 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  e a text string 
36e30 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a  in an encoding.*
36e40 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  * specified by t
36e50 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61  he fifth (and la
36e60 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77  st) parameter, w
36e70 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65  hich must be one
36e80 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  .** of [SQLITE_U
36e90 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
36ea0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
36eb0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
36ec0 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20  TE_UTF16LE]..** 
36ed0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
36ee0 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
36ef0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
36f00 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
36f10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
36f20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
36f30 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
36f40 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
36f50 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
36f60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
36f70 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
36f80 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
36f90 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
36fa0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
36fb0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
36fc0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
36fd0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
36fe0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
36ff0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
37000 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
37010 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37020 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
37030 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
37040 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
37050 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
37060 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
37070 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
37080 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
37090 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
370a0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
370b0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
370c0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
370d0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
370e0 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
370f0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
37100 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
37110 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
37120 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
37130 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
37140 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
37150 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
37160 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
37170 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
37180 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
37190 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
371a0 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
371b0 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
371c0 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
371d0 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
371e0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
371f0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
37200 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
37210 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
37220 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
37230 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
37240 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
37250 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
37260 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
37270 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
37280 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
37290 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
372a0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
372b0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
372c0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
372d0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
372e0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
372f0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
37300 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
37310 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
37320 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
37330 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
37340 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
37350 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
37360 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
37370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37380 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37390 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
373a0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
373b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
373c0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
373d0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
373e0 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
373f0 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
37400 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
37410 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
37420 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
37430 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
37440 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
37450 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
37460 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
37470 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
37480 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
37490 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
374a0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
374b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
374c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
374d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
374e0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
374f0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
37500 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
37510 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
37520 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
37530 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
37540 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
37550 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
37560 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
37570 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
37580 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
37590 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
375a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
375b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
375c0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
375d0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
375e0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
375f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37600 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
37610 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
37620 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
37630 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37640 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
37650 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
37660 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
37670 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
37680 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
37690 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
376a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
376b0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
376c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
376d0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
376e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
376f0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
37700 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
37710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
37720 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
37730 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
37740 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
37750 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37760 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
37770 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
37780 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
37790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
377a0 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
377b0 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
377c0 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
377d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
377e0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
377f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
37800 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
37810 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
37820 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
37830 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
37840 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
37850 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
37860 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37870 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37880 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
37890 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
378a0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
378b0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
378c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
378d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
378e0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
378f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37900 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
37910 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37920 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37930 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63  blob64(sqlite3_c
37940 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f  ontext*,const vo
37950 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  id*,.           
37960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37970 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76  sqlite3_uint64,v
37980 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37990 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
379a0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
379b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
379c0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
379d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
379e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
379f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
37a00 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
37a10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
37a20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37a30 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
37a40 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
37a50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
37a60 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
37a70 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
37a80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37a90 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
37aa0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
37ab0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37ac0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
37ad0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37ae0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
37af0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
37b00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37b10 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
37b20 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
37b30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37b40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
37b50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37b60 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
37b70 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
37b80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37b90 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
37ba0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
37bb0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
37bc0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
37bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37be0 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt64(sqlite3_con
37bf0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
37c00 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
37c10 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
37c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
37c30 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
37c40 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
37c50 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ding);.void sqli
37c60 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37c70 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
37c80 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37c90 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
37ca0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
37cb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37cc0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
37cd0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37ce0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
37cf0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
37d00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37d10 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
37d20 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
37d30 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
37d40 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
37d50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37d60 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
37d70 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
37d80 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
37d90 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
37da0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
37db0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74  xt*, int n);.int
37dc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37dd0 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
37de0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
37df0 69 74 65 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a  ite3_uint64 n);.
37e00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37e10 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 53 75  : Setting The Su
37e20 62 74 79 70 65 20 4f 66 20 41 6e 20 53 51 4c 20  btype Of An SQL 
37e30 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48  Function.** METH
37e40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
37e50 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ext.**.** The sq
37e60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
37e70 74 79 70 65 28 43 2c 54 29 20 66 75 6e 63 74 69  type(C,T) functi
37e80 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 73 75  on causes the su
37e90 62 74 79 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20  btype of.** the 
37ea0 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
37eb0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
37ec0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
37ed0 6e 5d 20 77 69 74 68 20 0a 2a 2a 20 5b 73 71 6c  n] with .** [sql
37ee0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 20  ite3_context] C 
37ef0 74 6f 20 62 65 20 74 68 65 20 76 61 6c 75 65 20  to be the value 
37f00 54 2e 20 20 4f 6e 6c 79 20 74 68 65 20 6c 6f 77  T.  Only the low
37f10 65 72 20 38 20 62 69 74 73 20 0a 2a 2a 20 6f 66  er 8 bits .** of
37f20 20 74 68 65 20 73 75 62 74 79 70 65 20 54 20 61   the subtype T a
37f30 72 65 20 70 72 65 73 65 72 76 65 64 20 69 6e 20  re preserved in 
37f40 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 73  current versions
37f50 20 6f 66 20 53 51 4c 69 74 65 3b 0a 2a 2a 20 68   of SQLite;.** h
37f60 69 67 68 65 72 20 6f 72 64 65 72 20 62 69 74 73  igher order bits
37f70 20 61 72 65 20 64 69 73 63 61 72 64 65 64 2e 0a   are discarded..
37f80 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** The number of
37f90 20 73 75 62 74 79 70 65 20 62 79 74 65 73 20 70   subtype bytes p
37fa0 72 65 73 65 72 76 65 64 20 62 79 20 53 51 4c 69  reserved by SQLi
37fb0 74 65 20 6d 69 67 68 74 20 69 6e 63 72 65 61 73  te might increas
37fc0 65 0a 2a 2a 20 69 6e 20 66 75 74 75 72 65 20 72  e.** in future r
37fd0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
37fe0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
37ff0 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70  e3_result_subtyp
38000 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
38010 74 2a 2c 75 6e 73 69 67 6e 65 64 20 69 6e 74 29  t*,unsigned int)
38020 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38030 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
38040 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
38050 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
38060 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
38070 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
38080 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
38090 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
380a0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
380b0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
380c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
380d0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
380e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
380f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
38100 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
38110 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
38120 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
38130 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38140 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
38150 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38160 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
38170 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
38180 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
38190 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
381a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
381b0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
381c0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
381d0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
381e0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
381f0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
38200 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
38210 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
38220 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
38230 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
38240 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
38250 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
38260 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
38270 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
38280 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
38290 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
382a0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
382b0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
382c0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
382d0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
382e0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
382f0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
38300 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
38310 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
38320 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
38330 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
38340 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
38350 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
38360 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
38370 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
38380 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
38390 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
383a0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
383b0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
383c0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
383d0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
383e0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
383f0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
38400 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
38410 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
38420 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
38430 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
38440 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
38450 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
38460 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
38470 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
38480 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
38490 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
384a0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
384b0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
384c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
384d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
384e0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
384f0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
38500 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
38510 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
38520 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
38530 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
38540 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
38550 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
38560 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
38570 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
38580 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
38590 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
385a0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
385b0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
385c0 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
385d0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
385e0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
385f0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
38600 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
38610 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
38620 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
38630 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
38640 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
38650 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
38660 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
38670 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
38680 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
38690 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
386a0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
386b0 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
386c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
386d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
386e0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
386f0 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
38700 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
38710 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
38720 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
38730 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
38740 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
38750 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
38760 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
38770 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
38780 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
38790 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
387a0 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
387b0 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
387c0 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
387d0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
387e0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
387f0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
38800 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
38810 6f 6e 64 2c 0a 2a 2a 20 7