/ Hex Artifact Content
Login

Artifact 070b49c253bd41607ec43505a16163aa4b537b83:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20  _IOERR_VNODE    
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29  _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20  _IOERR_AUTH     
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29  _IOERR | (28<<8)
5610: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5620: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5630: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5640: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5660: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5670: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5680: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5690: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56a0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
56b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56c0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56f0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
5700: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5710: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
5730: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5740: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5750: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5760: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5770: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5780: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5790: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57b0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
57c0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57d0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57f0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5800: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5810: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5830: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5850: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5870: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5880: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5890: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
58a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58b0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
58d0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
5900: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
5910: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5930: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5940: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5950: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5980: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59c0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
59d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59e0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a00: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5a10: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5a20: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a50: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a90: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5aa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ab0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5ac0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ad0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5ae0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5af0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b10: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5b30: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b50: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b60: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ba0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5bb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bc0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5be0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c00: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c60: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c70: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c80: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5ca0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5cb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5cc0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ce0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5d00: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5d20: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5d30: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5dc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5de0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5e00: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5e10: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5e20: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e30: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e50: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e60: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e70: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e80: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5ea0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5eb0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5ec0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ed0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5ef0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5f00: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5f30: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f40: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f70: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f80: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5fc0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6000: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6010: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6020: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6030: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6090: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
60a0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
60d0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60e0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6150: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6160: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6190: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
61a0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
61d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61e0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6210: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6220: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6260: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6270: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6280: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6290: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
62b0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
62c0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
62d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6300: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6310: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6320: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6330: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6360: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6380: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6390: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63a0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
63b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
63c0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
63d0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
63e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
63f0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6400: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6410: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6420: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6430: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6440: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6450: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6460: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6470: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6480: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6490: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
64a0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
64b0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
64c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
64d0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
64e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
64f0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6500: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6510: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6520: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6530: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6540: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6550: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6560: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6570: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6580: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6590: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
65a0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
65b0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
65c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
65d0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
65e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
65f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6600: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6610: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6620: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6630: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6640: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6650: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6660: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6670: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6680: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6690: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
66b0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
66c0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
66d0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
66e0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
66f0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6700: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6710: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6720: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6730: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6740: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6750: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6760: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6770: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6780: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6790: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
67a0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
67b0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
67c0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
67d0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
67e0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
67f0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6800: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6810: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6820: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6830: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6840: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6850: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6860: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6870: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6880: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6890: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
68a0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
68b0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
68c0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
68d0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
68e0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
68f0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6900: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6910: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6920: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6930: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6950: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6970: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6980: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6990: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
69a0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6aa0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6ab0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6b10: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6b20: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b80: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6b90: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6bb0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6bc0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bf0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6c00: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6c20: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6c30: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6c50: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6c60: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6c70: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6c80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6c90: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6ca0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6cb0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6cc0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6cd0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6ce0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6cf0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d00: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6d20: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6d30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d40: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6d50: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6d60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6d70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6d80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6d90: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6da0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6db0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6dc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6dd0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6de0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6df0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6e00: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6e10: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6e20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6e30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e40: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6e50: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6e60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6e70: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6e80: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6e90: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ea0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6eb0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6ec0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6ed0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ee0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6ef0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6f00: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6f10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6f20: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6f30: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f40: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6f50: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6f60: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6f70: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6f80: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6f90: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6fa0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6fb0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6fc0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6fd0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6fe0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6ff0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7000: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7010: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7020: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7030: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7040: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7050: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7060: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7070: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7080: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7090: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
70a0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
70b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
70c0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
70d0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
70e0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
70f0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7100: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7110: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7120: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7130: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7140: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7150: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7160: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7170: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7180: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7190: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
71a0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
71b0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
71c0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
71d0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
71e0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
71f0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7200: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7210: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7220: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7230: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7240: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7250: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7260: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7270: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7280: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7290: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
72a0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
72b0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
72c0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
72d0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
72e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7380: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7390: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
73a0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
73b0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
73c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
73d0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
73e0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
73f0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7400: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7410: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7420: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7430: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7440: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7450: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7460: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7470: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7480: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7490: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
74a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
74b0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
74c0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
74d0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
74e0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
74f0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7500: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7510: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7520: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7530: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7540: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7560: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7570: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7580: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7590: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
75a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
75b0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
75c0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
75d0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
75e0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
75f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7600: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7610: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7620: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7630: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7640: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7650: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7660: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7670: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7680: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7690: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
76a0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
76b0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
76c0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
76d0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
76e0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
76f0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7700: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7710: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7720: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7740: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7760: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7770: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7780: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7790: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
77a0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
77b0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
77c0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
77d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77e0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
77f0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7800: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7810: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7820: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7830: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7840: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7850: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7870: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7880: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7890: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
78a0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
78b0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
78c0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
78d0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
78e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
78f0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7900: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7910: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7920: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7930: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7940: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7950: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7960: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7970: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7980: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7990: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
79a0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
79b0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
79c0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
79d0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
79e0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
79f0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7a00: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7a10: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7a20: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7a30: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7a50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a60: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7a70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a80: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7a90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7aa0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7ab0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ac0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7ad0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7ae0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7af0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7b00: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7b10: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7b20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7b30: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b40: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7b50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7b60: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7b70: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7b80: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7b90: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7ba0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7bb0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7bc0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7bd0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7be0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7bf0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7c00: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7c10: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7c20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7c30: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c40: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7c50: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7c60: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7c70: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7c80: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7c90: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7cb0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7cc0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7cd0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7ce0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7cf0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7d00: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7d10: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7d20: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7d30: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d40: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7d50: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7d60: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7d70: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7d80: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7d90: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7da0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7db0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7dc0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7dd0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7de0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7df0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7e00: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7e10: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7e20: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7e30: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e40: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7e50: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7e60: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7e70: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7e80: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7e90: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7ea0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7eb0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7ec0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7ed0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ee0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7ef0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f00: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f10: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f20: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7f30: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f40: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7f50: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7f60: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7f70: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7f80: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7f90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7fa0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7fb0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7fc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7fd0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7fe0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7ff0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8000: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8010: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8020: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8030: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8040: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8050: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8060: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8070: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8080: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8090: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
80a0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
80b0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
80c0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
80d0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
80e0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
80f0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8100: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8110: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8120: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8130: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8140: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8150: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8160: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8170: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <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 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <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 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <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 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
81e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81f0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8200: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8210: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8220: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8230: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8250: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8260: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8270: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8290: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
82a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
82b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
82d0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
82e0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
82f0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8300: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8310: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8320: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8330: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8340: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8350: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8360: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8370: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8380: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8390: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
83a0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
83b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
83c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
83d0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
83e0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
83f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8400: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8410: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8420: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8430: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8440: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8450: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8460: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8480: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8490: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
84a0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
84b0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
84c0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
84d0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
84e0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
84f0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8500: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8510: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8520: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8530: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8540: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8550: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8560: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8570: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8580: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8590: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
85a0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
85b0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
85c0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
85d0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
85e0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
85f0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8600: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8610: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8620: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8630: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8640: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8650: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8660: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8680: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8690: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86a0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
86b0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
86c0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
86d0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
86e0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
86f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8710: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8720: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8730: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8740: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8750: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8760: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8770: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8780: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8790: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
87a0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
87b0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
87c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
87d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
87e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87f0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8800: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8810: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8820: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8830: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8840: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8850: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8860: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8870: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8890: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
88a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
88c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
88d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88e0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
88f0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8910: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8920: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8930: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8940: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8950: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8960: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8970: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8980: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8990: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
89a0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
89b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89c0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
89d0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
89e0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
89f0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a00: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8a30: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a40: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8a50: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8a60: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8a70: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8a80: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8a90: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8aa0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ab0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8ac0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8ad0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8ae0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8af0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b00: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b10: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b20: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8b30: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b40: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8b50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8b60: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8b70: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8b80: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8b90: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8ba0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8bb0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8bc0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8bd0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8be0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8bf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8c00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8c20: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8c30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c40: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8c50: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8c60: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8c70: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8c80: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8c90: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8ca0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8cb0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8cc0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8cd0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ce0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8cf0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8d00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8d10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8d20: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8d30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d40: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8d50: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8d60: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8d70: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8d80: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8d90: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8da0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8db0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8dc0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8dd0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8de0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8df0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8e00: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8e10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8e20: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8e30: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e40: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8e50: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8e60: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8e70: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e80: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e90: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8ea0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8eb0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8ec0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8ed0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ee0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8ef0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8f00: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8f10: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8f20: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8f30: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f40: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8f50: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8f60: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8f70: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f80: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f90: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8fa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8fb0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8fc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8fd0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8ff0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9000: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9010: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9020: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9030: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9040: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9050: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9060: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9070: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9080: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9090: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
90a0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
90b0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
90c0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
90d0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
90e0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
90f0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9100: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9110: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9120: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9130: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9140: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9150: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9160: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9170: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9180: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9190: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
91a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
91b0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
91c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
91d0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
91e0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
91f0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9200: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9210: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9220: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9230: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9240: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9250: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9260: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9270: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9280: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9290: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
92a0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
92b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92c0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
92d0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
92e0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
92f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9300: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9310: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9320: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9330: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9340: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9350: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9360: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9370: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9380: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9390: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
93a0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
93b0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
93c0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
93d0: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
93e0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
93f0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9400: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9410: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9420: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9430: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9440: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9450: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9460: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9470: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9480: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9490: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
94a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
94b0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
94c0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
94d0: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
94e0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
94f0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9500: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9510: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9520: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9530: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9540: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9550: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9560: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9570: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9580: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9590: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
95a0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
95b0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
95c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
95d0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
95e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
95f0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9600: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9610: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9620: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9630: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9640: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9650: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9660: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9670: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9680: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9690: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
96a0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
96b0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
96c0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
96d0: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
96e0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
96f0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9700: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9710: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9720: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9730: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9740: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9750: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9760: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9770: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9780: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9790: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
97a0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
97b0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
97c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
97d0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
97e0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
97f0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9800: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9810: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9820: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9830: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9850: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9860: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9880: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9890: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
98a0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
98b0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
98c0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
98d0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
98e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
98f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9900: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9910: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9920: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9930: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9940: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9950: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9960: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9970: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9980: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9990: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
99a0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
99b0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
99c0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
99d0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
99e0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
99f0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9a00: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9a10: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9a20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9a30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9a40: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9a50: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9a60: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9a70: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a80: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a90: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9aa0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9ab0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9ac0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9ad0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9ae0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9af0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9b00: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9b10: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9b20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9b30: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9b40: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9b50: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9b60: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9b70: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b80: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b90: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9ba0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9bb0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9bc0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9bd0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9be0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9bf0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9c00: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9c10: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9c20: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9c30: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9c40: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9c50: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9c60: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9c70: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c80: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9ca0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9cb0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9cc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9cd0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9ce0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9cf0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9d00: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9d10: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9d20: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9d30: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9d40: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9d50: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9d60: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9d70: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d80: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d90: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9da0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9db0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9dc0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9dd0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9de0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9df0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9e00: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9e10: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9e20: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9e30: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9e40: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9e50: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9e60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9e70: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e80: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e90: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9ea0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9eb0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9ec0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9ed0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ee0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9ef0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9f00: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9f10: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9f20: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9f30: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9f40: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9f50: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9f60: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9f70: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f90: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9fa0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9fb0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9fc0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9fd0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9fe0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9ff0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a000: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a010: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a020: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a030: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a040: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a070: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a080: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a090: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a0a0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a0b0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a0c0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a0d0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a0e0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a0f0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a100: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a110: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a120: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a140: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a150: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a160: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a170: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a180: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a190: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a1a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a1b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a1c0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a1d0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a1e0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a1f0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a200: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a210: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a220: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a230: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a240: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a250: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a260: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a270: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a280: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a290: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a2a0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a2b0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a2d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a2e0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a2f0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a300: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a310: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a320: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a330: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a340: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a350: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a360: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a370: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a380: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a390: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a3a0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a3b0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a3c0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a3d0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a3e0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a3f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a400: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a410: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a420: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a430: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a440: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a450: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a460: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a470: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a480: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a490: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a4a0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a4b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a4c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a4d0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a4e0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a4f0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a500: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a510: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a520: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a530: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a540: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a550: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a560: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a570: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a580: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a590: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a5a0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a5b0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a5c0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a5d0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a5e0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a5f0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a600: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a610: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a620: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a630: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a640: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a650: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a660: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a670: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a680: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a690: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a6a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a6b0: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a6c0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a6d0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a6e0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a6f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a700: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a710: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a720: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a730: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a740: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a750: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a760: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a770: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a780: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a790: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a7a0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a7b0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a7c0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a7d0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a7e0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a7f0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a800: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a810: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a820: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a830: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a840: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a850: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a860: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a870: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a880: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a890: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a8a0: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a8b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a8c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a8d0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a8e0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a8f0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a900: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a910: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a920: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a930: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a940: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a950: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a960: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a970: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a980: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a990: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a9a0: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a9b0: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a9c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a9d0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a9e0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a9f0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
aa00: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
aa10: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
aa20: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
aa30: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
aa40: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
aa50: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
aa60: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
aa70: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
aa80: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
aa90: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
aaa0: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
aab0: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
aac0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
aad0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
aae0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
aaf0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
ab00: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
ab10: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
ab20: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
ab30: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
ab40: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
ab50: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
ab60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab70: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab80: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab90: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
aba0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
abb0: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
abc0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
abd0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
abe0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
abf0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
ac00: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
ac10: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
ac20: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
ac30: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
ac40: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
ac50: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
ac60: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac80: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac90: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
aca0: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
acb0: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
acc0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
acd0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
ace0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
acf0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ad00: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
ad10: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
ad20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
ad30: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
ad40: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
ad50: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ad60: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
ad70: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad80: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad90: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ada0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
adb0: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
adc0: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
add0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ade0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
adf0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ae00: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ae10: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ae20: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
ae30: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ae40: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
ae50: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ae60: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ae70: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae80: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae90: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
aea0: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
aeb0: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
aec0: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
aed0: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
aee0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
aef0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
af00: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
af10: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
af20: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
af30: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
af40: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
af50: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
af60: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
af70: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af80: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af90: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
afa0: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
afb0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
afc0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
afd0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
afe0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
aff0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
b000: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b010: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
b020: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
b030: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b040: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b050: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b060: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b070: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b080: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b090: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b0a0: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b0b0: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b0c0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b0d0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b0e0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b0f0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b100: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b110: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b120: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b130: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b140: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b150: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b160: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b170: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b180: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b190: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b1a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b1b0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b1c0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b1d0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b1e0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b1f0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b200: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b210: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b220: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b230: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b240: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b250: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b260: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b270: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b280: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b290: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b2a0: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b2b0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b2c0: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b2d0: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b2e0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b300: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b310: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b320: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b330: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b340: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b350: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b360: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b370: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b380: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b390: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b3a0: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b3b0: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b3c0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b3d0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b3e0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b3f0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b400: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b410: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b420: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b430: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b440: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b450: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b460: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b470: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b480: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b490: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b4a0: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b4b0: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b4c0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b4d0: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b4e0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b4f0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b500: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b510: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b520: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b530: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b540: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b550: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b560: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b570: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b580: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b590: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b5a0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b5b0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b5c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b5d0: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b5e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b5f0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b600: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b610: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b620: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b630: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b640: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b650: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b660: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b670: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b680: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b690: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b6a0: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b6b0: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b6c0: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b6d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b6e0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b6f0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b700: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b710: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b720: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b730: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
b740: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
b750: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
b760: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
b770: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
b780: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
b790: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
b7a0: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
b7b0: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
b7c0: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
b7d0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b7e0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
b7f0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
b800: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
b810: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
b820: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b830: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
b840: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
b850: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
b860: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
b870: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
b880: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
b890: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
b8a0: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
b8b0: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
b8c0: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
b8d0: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
b8e0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
b8f0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
b900: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
b910: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
b920: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
b930: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
b940: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
b950: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
b960: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
b970: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
b980: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
b990: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
b9a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b9b0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
b9c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b9d0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
b9e0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
b9f0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
ba00: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
ba10: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
ba20: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
ba30: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
ba40: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
ba50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
ba60: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
ba70: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
ba80: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
ba90: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
baa0: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
bab0: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
bac0: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
bad0: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
bae0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
baf0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
bb00: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
bb10: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
bb20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
bb30: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
bb40: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
bb50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
bb60: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
bb70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
bb80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
bb90: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bba0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
bbb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
bbc0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
bbd0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bbe0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
bbf0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
bc00: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bc10: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bc20: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bc30: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bc40: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
bc50: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bc60: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bc70: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bc80: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bc90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bca0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bcb0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bcc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bcd0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bce0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bcf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bd00: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bd10: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bd20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bd30: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
bd40: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
bd50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd60: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
bd70: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
bd80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd90: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
bda0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
bdb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bdc0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
bdd0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
bde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
bdf0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
be00: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
be10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
be20: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
be30: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
be40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
be50: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
be60: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
be80: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
be90: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
bea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
beb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bec0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
bed0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
bee0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
bef0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
bf00: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
bf10: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
bf20: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
bf30: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
bf40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
bf50: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bf60: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
bf70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
bf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf90: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
bfa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
bfb0: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
bfc0: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bfd0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
bfe0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c000: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
c010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
c020: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c030: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c040: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c050: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c060: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c070: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c080: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c090: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c0a0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c0b0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c0c0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c0d0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c0e0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c0f0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c100: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c110: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c120: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c130: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c140: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c150: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c160: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c170: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c180: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c190: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c1a0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c1b0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c1c0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c1d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c1e0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c1f0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c200: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c210: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c220: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c230: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
c240: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
c250: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c260: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c270: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c280: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
c290: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
c2a0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
c2b0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
c2c0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
c2d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
c2e0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
c2f0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
c300: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
c310: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
c320: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
c330: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
c340: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
c350: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
c360: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
c370: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
c380: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
c390: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
c3a0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
c3b0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
c3c0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
c3d0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
c3e0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
c3f0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
c400: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
c410: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
c420: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
c430: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c440: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
c450: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
c460: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
c470: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
c480: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
c490: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c4a0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
c4b0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
c4c0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
c4d0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c4e0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
c4f0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
c500: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
c510: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
c520: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
c530: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
c540: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
c550: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
c560: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
c570: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
c580: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
c590: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
c5a0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
c5b0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
c5c0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
c5d0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
c5e0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
c5f0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
c600: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
c610: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
c620: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
c630: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c640: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
c650: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
c660: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
c670: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c680: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
c690: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
c6a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
c6b0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c6c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
c6d0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
c6e0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
c6f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c700: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
c710: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
c720: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
c730: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
c740: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
c750: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
c760: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
c770: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
c780: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c790: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c7a0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
c7b0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
c7c0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
c7d0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
c7e0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
c7f0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
c800: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
c810: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
c820: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
c830: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
c840: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
c850: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
c860: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
c870: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
c880: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
c890: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
c8a0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c8b0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
c8c0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
c8d0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
c8e0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
c8f0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
c900: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
c910: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
c920: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
c930: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
c940: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c950: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
c960: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
c970: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
c980: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
c990: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
c9a0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
c9b0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
c9c0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
c9d0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
c9e0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
c9f0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
ca00: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
ca10: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
ca20: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
ca30: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
ca40: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
ca50: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
ca60: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
ca70: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
ca80: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
ca90: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
caa0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
cab0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
cac0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
cad0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
cae0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
caf0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
cb00: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
cb10: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
cb20: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
cb30: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
cb40: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
cb50: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
cb60: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
cb70: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
cb80: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
cb90: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
cba0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
cbb0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
cbc0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cbd0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
cbe0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
cbf0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
cc00: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
cc10: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
cc20: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
cc30: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
cc40: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
cc50: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
cc60: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
cc70: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
cc80: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
cc90: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
cca0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
ccb0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
ccc0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
ccd0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
cce0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
ccf0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
cd00: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
cd10: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cd20: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
cd30: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
cd40: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
cd50: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
cd60: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
cd70: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cd80: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
cd90: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
cda0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
cdb0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
cdc0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
cdd0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
cde0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
cdf0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ce00: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
ce10: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ce20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
ce30: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ce40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
ce50: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ce60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ce70: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
ce80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ce90: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
cea0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ceb0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
cec0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ced0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
cee0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
cef0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
cf00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
cf10: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
cf20: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
cf30: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
cf40: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
cf50: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
cf60: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
cf70: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
cf80: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
cf90: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
cfa0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
cfb0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
cfc0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
cfd0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
cfe0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
cff0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
d000: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
d010: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
d020: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
d030: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d050: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d060: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d070: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d080: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d090: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d0a0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d0b0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d0c0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d0d0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d0e0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d0f0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d100: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d110: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d120: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d130: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d140: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d150: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d170: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d180: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d190: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d1a0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d1c0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d1d0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d1e0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d1f0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d200: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d210: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d220: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d230: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
d240: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
d250: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
d260: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
d270: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
d280: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
d290: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d2a0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
d2b0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
d2c0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
d2d0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
d2e0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
d2f0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
d300: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
d310: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
d320: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
d330: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
d340: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
d350: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
d360: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
d370: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
d380: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
d390: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d3a0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
d3b0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
d3c0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
d3d0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
d3e0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
d3f0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
d400: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
d410: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
d420: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d430: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
d440: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
d450: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
d460: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
d470: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
d480: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
d490: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
d4a0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
d4b0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
d4c0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
d4d0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
d4e0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
d4f0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
d500: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
d510: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
d520: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
d530: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
d540: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
d550: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
d560: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d570: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
d580: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d590: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
d5a0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
d5b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d5c0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
d5d0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
d5e0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
d5f0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
d600: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
d610: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
d620: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
d630: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
d640: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
d650: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
d660: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
d670: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
d680: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
d690: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
d6a0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
d6b0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
d6c0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
d6d0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
d6e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d6f0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
d700: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
d710: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
d720: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d730: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
d740: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d750: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
d760: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
d770: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d780: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
d790: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d7a0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
d7b0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
d7c0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
d7d0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
d7e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
d7f0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
d800: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
d810: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
d820: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
d830: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
d840: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
d850: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
d860: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
d870: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
d880: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
d890: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
d8a0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d8b0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
d8c0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
d8d0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
d8e0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
d8f0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
d900: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
d910: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
d920: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
d930: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
d940: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
d950: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
d960: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
d970: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
d980: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
d990: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d9a0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
d9b0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
d9c0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
d9d0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
d9e0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
d9f0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
da00: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
da10: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
da20: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
da30: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
da40: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
da50: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
da60: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
da70: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
da80: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
da90: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
daa0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
dab0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
dac0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
dad0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
dae0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
daf0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
db00: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
db10: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
db20: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
db30: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
db40: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
db50: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
db60: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
db70: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
db80: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
db90: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
dba0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
dbb0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
dbc0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
dbd0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
dbe0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
dbf0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dc00: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
dc10: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
dc20: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
dc30: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
dc40: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
dc50: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
dc60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
dc70: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
dc80: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
dc90: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
dca0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dcb0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
dcc0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
dcd0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
dce0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
dcf0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
dd00: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
dd10: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
dd20: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
dd30: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
dd40: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
dd50: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
dd60: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
dd70: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
dd80: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
dd90: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
dda0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
ddb0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
ddc0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
ddd0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
dde0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
ddf0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
de00: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
de10: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
de20: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
de30: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
de40: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
de50: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
de60: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
de70: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
de80: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
de90: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
dea0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
deb0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
dec0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
ded0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
dee0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
def0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
df00: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
df10: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
df20: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
df30: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
df40: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
df50: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
df60: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
df70: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
df80: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
df90: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
dfa0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
dfb0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
dfc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
dfd0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
dfe0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
dff0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
e000: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
e010: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
e020: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
e030: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e040: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e050: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e060: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e070: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e080: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e090: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e0a0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e0b0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e0c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e0d0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e0e0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e0f0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e100: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e110: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e120: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e130: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e140: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e150: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e160: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e170: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e180: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e190: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e1a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e1b0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e1c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e1d0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e1e0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e1f0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e200: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e210: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e220: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e230: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
e240: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
e250: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e260: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
e270: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
e280: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
e290: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
e2a0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
e2b0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
e2c0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e2d0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e2e0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
e2f0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
e300: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
e310: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
e320: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(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 73 79 6e 63 44 69  Name, int syncDi
e350: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
e360: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
e370: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e380: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
e390: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
e3a0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
e3b0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
e3c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e3d0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
e3e0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e3f0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
e400: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e410: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
e420: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
e430: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
e440: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e450: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
e460: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
e470: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
e480: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
e490: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
e4a0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
e4b0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
e4c0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
e4d0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
e4e0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
e4f0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
e500: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
e510: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
e520: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
e530: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
e540: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e550: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e560: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
e570: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
e580: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e590: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
e5a0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e5b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e5c0: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
e5d0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e5e0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
e5f0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
e600: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
e610: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
e620: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
e630: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e640: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
e650: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
e660: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
e670: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e680: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e690: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
e6a0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e6b0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
e6c0: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
e6d0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
e6e0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
e6f0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
e700: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e710: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e720: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
e730: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
e740: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
e750: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
e760: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e770: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e780: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
e790: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
e7a0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e7b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e7c0: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
e7d0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e7e0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e7f0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
e800: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e810: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
e820: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
e830: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
e840: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
e850: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
e860: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
e870: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
e880: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
e890: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e8a0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e8b0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
e8c0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
e8d0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
e8e0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
e8f0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
e900: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
e910: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e920: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
e930: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
e940: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
e950: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
e960: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
e970: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
e980: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
e990: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e9a0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
e9b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
e9c0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
e9d0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
e9e0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
e9f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ea00: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
ea10: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
ea20: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ea30: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
ea40: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
ea50: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
ea60: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
ea70: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ea80: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ea90: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
eaa0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
eab0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
eac0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ead0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
eae0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
eaf0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
eb00: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
eb10: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
eb20: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
eb30: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
eb40: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
eb50: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
eb60: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
eb70: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
eb80: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
eb90: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
eba0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
ebb0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
ebc0: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
ebd0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
ebe0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
ebf0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
ec00: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
ec10: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
ec20: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
ec30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ec40: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
ec50: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ec60: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
ec70: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
ec80: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ec90: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
eca0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ecb0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
ecc0: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
ecd0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ece0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
ecf0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ed00: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ed10: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
ed20: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
ed30: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
ed40: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
ed50: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ed60: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
ed70: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ed80: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
ed90: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
eda0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
edb0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
edc0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
edd0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ede0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
edf0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ee00: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
ee10: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
ee20: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
ee30: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
ee40: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ee50: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ee60: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
ee70: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ee80: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ee90: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
eea0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
eeb0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
eec0: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
eed0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
eee0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
eef0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
ef00: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
ef10: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
ef20: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ef30: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ef40: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
ef50: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ef60: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
ef70: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
ef80: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ef90: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
efa0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
efb0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
efc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
efd0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
efe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
eff0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
f000: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f010: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
f020: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
f030: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f040: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f050: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f060: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f070: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f080: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f090: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f0a0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f0b0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f0c0: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f0d0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f0e0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f0f0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f100: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f110: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f120: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f130: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f140: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f150: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f160: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f170: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f180: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f190: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f1a0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f1b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f1c0: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f1d0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f1e0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f1f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f200: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f210: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f220: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f230: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
f240: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f250: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
f260: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
f270: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
f280: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
f290: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
f2a0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
f2b0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
f2c0: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
f2d0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
f2e0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
f2f0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
f300: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
f310: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f320: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f330: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f340: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f350: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
f360: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
f370: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f380: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f390: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
f3a0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
f3b0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
f3c0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
f3d0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
f3e0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
f3f0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
f400: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
f410: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
f420: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
f430: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
f440: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f450: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
f460: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
f470: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
f480: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f490: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
f4a0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f4b0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
f4c0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
f4d0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f4e0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
f4f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f500: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
f510: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f520: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
f530: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
f540: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f550: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
f560: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
f570: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
f580: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
f590: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f5a0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
f5b0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f5c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
f5d0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
f5e0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
f5f0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
f600: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
f610: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
f620: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
f630: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
f640: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
f650: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
f660: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
f670: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f680: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
f690: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
f6a0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
f6b0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
f6c0: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
f6d0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
f6e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f6f0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
f700: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
f710: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f720: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
f730: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f740: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
f750: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
f760: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
f770: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
f780: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
f790: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f7a0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
f7b0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f7c0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
f7d0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
f7e0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
f7f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
f800: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
f810: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
f820: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
f830: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
f840: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
f850: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
f860: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
f870: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
f880: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
f890: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
f8a0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f8b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f8c0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
f8d0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
f8e0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
f8f0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
f900: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
f910: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
f920: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
f930: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f940: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f950: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
f960: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
f970: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
f980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f990: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
f9a0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
f9b0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
f9c0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
f9d0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
f9e0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
f9f0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
fa00: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
fa10: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
fa20: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
fa30: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
fa40: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
fa50: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
fa60: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
fa70: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
fa80: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
fa90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
faa0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
fab0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
fac0: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
fad0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fae0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
faf0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
fb00: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
fb10: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
fb20: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
fb30: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
fb40: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
fb50: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
fb60: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
fb70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fb80: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
fb90: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
fba0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fbb0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
fbc0: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
fbd0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
fbe0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
fbf0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
fc00: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
fc10: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
fc20: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
fc30: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
fc40: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
fc50: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
fc60: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
fc70: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fc80: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
fc90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fca0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
fcb0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
fcc0: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
fcd0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fce0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
fcf0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
fd00: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fd10: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
fd20: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
fd30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
fd40: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
fd50: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
fd60: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
fd70: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
fd80: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
fd90: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
fda0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
fdb0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
fdc0: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
fdd0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
fde0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
fdf0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
fe00: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
fe10: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
fe20: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
fe30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
fe40: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
fe50: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
fe60: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
fe70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fe80: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
fe90: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
fea0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
feb0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
fec0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fed0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fee0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
fef0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
ff00: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
ff10: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
ff20: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
ff30: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
ff40: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
ff50: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ff60: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
ff70: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ff80: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
ff90: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ffa0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
ffb0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
ffc0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ffd0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
ffe0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
fff0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
10000 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
10010 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
10020 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
10030 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10040 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10050 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10060 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10070 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10080 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10090 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
100a0 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
100b0 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
100c0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
100d0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
100e0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
100f0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
10100 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
10110 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
10120 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
10130 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10140 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10150 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10160 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10170 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10180 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10190 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
101a0 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
101b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
101c0 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
101d0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
101e0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
101f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
10200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10210 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
10220 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10230 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10240 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10250 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10260 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10280 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10290 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
102a0 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
102b0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
102c0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
102d0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
102e0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
102f0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10300 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10310 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10320 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10330 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10340 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10350 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10360 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10370 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10380 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10390 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
103a0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
103b0 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
103c0 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
103d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
103e0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
103f0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10400 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
10410 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
10420 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
10430 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10440 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
10450 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10460 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10470 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
10480 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
10490 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
104a0 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
104b0 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
104c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
104d0 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
104e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
104f0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
10500 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
10510 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
10520 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10530 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
10540 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10550 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
10560 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
10570 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
10580 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
10590 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
105a0 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
105b0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
105c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
105d0 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
105e0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
105f0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
10600 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10610 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10620 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10630 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
10640 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10650 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
10660 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
10670 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
10680 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
10690 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
106a0 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
106b0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
106c0 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
106d0 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
106e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
106f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
10700 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
10710 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
10720 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10730 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10740 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
10750 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
10760 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
10770 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
10780 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
10790 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
107a0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
107b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
107c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
107d0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
107e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
107f0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
10810 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
10820 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
10830 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10840 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10850 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
10860 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
10870 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
10880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
10890 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
108a0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
108b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
108c0 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
108d0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
108e0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
108f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10900 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
10910 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10920 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
10930 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10940 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
10950 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
10960 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
10970 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10980 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
10990 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
109a0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
109b0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
109c0 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
109d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
109e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
109f0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10a00 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
10a10 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
10a20 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
10a30 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10a40 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
10a50 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
10a60 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
10a70 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
10a80 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
10a90 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
10aa0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10ab0 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10ac0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10ad0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10af0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10b00 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
10b10 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10b20 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
10b30 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
10b40 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
10b50 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
10b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10b70 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
10b80 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
10b90 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
10ba0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10bb0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10bc0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10bd0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10be0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10bf0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10c00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10c10 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
10c20 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10c30 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
10c40 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
10c50 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
10c60 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
10c70 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
10c80 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10c90 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
10ca0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10cb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10cc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10cd0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10ce0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10cf0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10d00 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
10d10 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
10d20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10d30 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
10d40 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
10d50 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
10d60 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
10d70 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
10d80 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
10d90 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
10da0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10db0 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10dc0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10dd0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10de0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10df0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10e00 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
10e10 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
10e20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
10e30 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
10e40 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10e50 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
10e60 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
10e70 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
10e80 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
10e90 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
10ea0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10eb0 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10ec0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10ed0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10ee0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10ef0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10f00 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
10f10 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
10f20 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
10f30 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
10f40 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
10f50 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
10f60 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
10f70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
10f80 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
10f90 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
10fa0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10fb0 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10fc0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10fd0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10fe0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10ff0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
11000 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
11010 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
11020 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
11030 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11040 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11050 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11060 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11070 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11080 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11090 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
110a0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
110b0 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
110c0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
110d0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
110e0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
110f0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
11100 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
11110 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
11120 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
11130 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11150 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11160 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11170 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11180 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
111a0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
111b0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
111c0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
111d0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
111e0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
111f0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
11200 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
11210 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
11220 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
11230 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11240 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11250 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11260 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11270 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11280 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11290 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
112a0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
112b0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
112c0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
112d0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
112e0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
112f0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
11300 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
11310 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
11320 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
11330 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11340 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11350 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11360 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11370 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11380 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11390 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
113a0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
113b0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
113c0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
113d0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
113e0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
113f0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
11400 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11410 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
11420 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
11430 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11440 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11450 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11460 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11470 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11480 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11490 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
114a0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
114b0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
114c0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
114d0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
114e0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
114f0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
11500 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
11510 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
11520 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
11530 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11540 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11550 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11560 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11570 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11580 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11590 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
115a0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
115b0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
115c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
115d0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
115e0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
115f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
11600 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11610 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11620 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
11630 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11640 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11650 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11660 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11670 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11680 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
116a0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
116b0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
116c0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
116d0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
116e0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
116f0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11700 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11710 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11720 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11730 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11740 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11750 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11760 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11770 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11780 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11790 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
117a0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
117b0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
117c0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
117d0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
117e0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
117f0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11810 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11820 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11830 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
11840 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
11850 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
11860 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
11870 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
11880 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
11890 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
118a0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
118b0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
118c0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
118d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
118e0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
118f0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
11900 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
11910 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
11920 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
11930 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
11940 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
11950 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
11960 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11970 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
11980 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
11990 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
119a0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
119b0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
119c0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
119d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
119e0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
119f0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
11a00 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
11a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11a20 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
11a30 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
11a40 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
11a50 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
11a60 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
11a70 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
11a80 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
11a90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
11aa0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11ab0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11ac0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11ad0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11ae0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11af0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11b00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11b10 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11b20 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11b30 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11b40 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
11b50 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
11b60 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
11b70 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
11b80 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
11b90 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
11ba0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11bb0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11bc0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11bd0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11be0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11bf0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11c00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11c10 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11c20 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11c30 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11c40 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
11c50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
11c60 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11c70 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
11c80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11c90 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
11ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11cb0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11cc0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11cd0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11ce0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11cf0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11d00 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11d10 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11d20 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11d30 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11d40 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
11d50 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
11d60 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11d70 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
11d80 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
11d90 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
11da0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11db0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11dc0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11dd0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11de0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11df0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11e00 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11e10 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11e20 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11e30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11e40 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
11e50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
11e60 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11e70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
11e80 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11e90 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
11ea0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11eb0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11ec0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11ed0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11ee0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11ef0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11f00 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11f10 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11f20 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11f30 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11f40 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11f50 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11f60 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11f70 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11f80 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11f90 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
11fa0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11fb0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11fc0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11fe0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11ff0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12000 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
12010 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
12020 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
12030 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12040 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12050 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12070 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12080 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12090 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
120a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
120b0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
120c0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
120d0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
120e0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
120f0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
12100 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
12110 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12120 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
12130 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12140 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12150 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12160 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12170 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12180 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12190 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
121a0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
121b0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
121c0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
121d0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
121e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
121f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12200 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12210 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12220 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
12230 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12240 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12250 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12270 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12280 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12290 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
122a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
122b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
122c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
122d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
122e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
122f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12300 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
12310 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12320 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
12330 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12340 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12350 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12360 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12380 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12390 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
123a0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
123b0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
123c0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
123d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
123e0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
123f0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
12400 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12410 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
12420 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
12430 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12440 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12460 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12470 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12480 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12490 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
124a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
124b0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
124c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
124d0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
124e0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
124f0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
12500 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12510 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12520 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12530 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12540 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12550 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12560 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12570 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12580 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12590 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
125a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
125b0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
125c0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
125d0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
125e0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
125f0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12610 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12630 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12650 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12660 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12670 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12680 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12690 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
126a0 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
126b0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
126c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
126d0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
126e0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
126f0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12700 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12710 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
12720 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12730 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12740 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12750 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12760 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12770 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12780 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12790 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
127a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
127b0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
127c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
127d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
127e0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
127f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12800 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12810 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12820 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12830 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
12840 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12850 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12860 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
12870 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
12880 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12890 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
128a0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
128b0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
128c0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
128d0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
128e0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
128f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12900 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
12910 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
12920 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
12930 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
12940 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12950 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
12960 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12970 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12980 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
12990 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
129a0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
129b0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
129c0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
129d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
129e0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
129f0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12a00 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
12a10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12a20 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12a30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12a40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
12a50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12a70 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
12a80 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12a90 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
12aa0 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
12ab0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
12ac0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
12ad0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
12ae0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
12af0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12b00 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
12b10 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
12b20 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12b30 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
12b40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
12b50 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
12b60 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
12b70 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
12b80 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
12b90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
12ba0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
12bb0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
12bc0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
12bd0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
12be0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
12bf0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
12c00 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
12c10 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
12c20 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
12c30 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12c40 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
12c50 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
12c60 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
12c70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
12c80 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
12c90 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
12ca0 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
12cb0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12cc0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12cd0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
12ce0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12d00 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
12d10 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12d20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12d30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12d40 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
12d50 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12d60 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12d70 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
12d80 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
12d90 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
12da0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12db0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
12dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12dd0 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
12de0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
12df0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
12e00 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
12e10 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
12e20 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
12e30 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
12e40 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
12e50 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
12e60 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
12e70 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12e80 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12e90 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
12ea0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12eb0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
12ec0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
12ed0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
12ee0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
12ef0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12f00 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
12f10 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
12f20 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
12f30 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
12f40 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
12f50 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
12f60 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
12f70 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
12f80 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
12f90 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
12fa0 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
12fb0 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
12fc0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
12fd0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12fe0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12ff0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13000 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13010 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
13020 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13030 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13040 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13050 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13060 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13070 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13080 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13090 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
130a0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
130b0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
130c0 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
130d0 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
130e0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
130f0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
13100 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
13110 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
13120 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
13130 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13140 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13150 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13160 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13170 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13180 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13190 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
131a0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
131b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
131c0 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
131d0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
131e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
131f0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
13200 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13210 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
13220 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13230 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
13240 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
13250 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
13260 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
13270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
13280 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
13290 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
132a0 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
132b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
132c0 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
132d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
132e0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
132f0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
13300 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20  FIG_PCACHE2].** 
13310 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13320 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  tion..** ^There 
13330 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13340 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
13350 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
13360 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
13370 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
13380 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
13390 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
133a0 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
133b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
133c0 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
133d0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
133e0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
133f0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
13400 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
13410 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
13420 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
13430 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
13440 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
13450 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
13460 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
13470 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
13480 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
13490 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
134a0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
134b0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
134c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
134d0 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a  _HDRSZ] option .
134e0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
134f0 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74  onfig()]..** ^It
13500 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
13510 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
13520 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
13530 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
13540 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
13550 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13560 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
13570 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
13580 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
13590 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  yte aligned bloc
135a0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74  k of memory that
135b0 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20  .** is at least 
135c0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
135d0 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20  mory, otherwise 
135e0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
135f0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
13600 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ned..** ^SQLite 
13610 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
13620 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
13630 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13640 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
13650 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
13660 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
13670 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
13680 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
13690 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
136a0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
136b0 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
136c0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
136d0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
136e0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
136f0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
13700 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13710 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
13720 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
13730 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13750 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
13760 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
13770 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13780 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13790 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
137a0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
137b0 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
137c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
137d0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
137e0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
137f0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
13800 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
13810 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
13820 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13830 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
13840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13850 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
13860 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13870 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
13880 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
13890 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
138a0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
138b0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
138c0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
138d0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
138e0 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
138f0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
13900 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
13910 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
13920 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
13930 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13940 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
13950 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
13960 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
13970 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
13980 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
13990 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
139a0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
139b0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
139c0 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
139d0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
139e0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
139f0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
13a00 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
13a10 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
13a20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
13a30 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
13a40 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
13a50 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
13a60 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
13a70 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
13a80 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
13a90 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
13aa0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
13ab0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13ac0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
13ad0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13ae0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13af0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13b00 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13b10 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13b20 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13b30 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13b40 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
13b50 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
13b60 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
13b70 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
13b80 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
13b90 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
13ba0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13bb0 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13bc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13bd0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
13be0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13bf0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
13c00 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13c10 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
13c20 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
13c30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13c40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13c50 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13c60 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
13c70 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13c90 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
13ca0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13cb0 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
13cc0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13cd0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13ce0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13cf0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13d00 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
13d10 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
13d20 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
13d30 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
13d40 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
13d50 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
13d60 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
13d70 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
13d80 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
13d90 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
13da0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13db0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13dc0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
13dd0 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
13de0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
13df0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
13e00 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
13e10 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13e20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13e30 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13e40 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13e50 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13e60 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
13e70 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
13e80 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
13e90 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
13ea0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
13eb0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
13ec0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
13ed0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
13ee0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
13ef0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13f00 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13f10 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13f20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13f30 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13f40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13f50 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
13f60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13f70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13f80 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
13f90 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13fa0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
13fb0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13fc0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13fe0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13ff0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
14000 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14010 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
14020 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
14030 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
14040 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
14050 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
14060 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
14070 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
14080 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
14090 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
140a0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
140b0 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
140c0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
140d0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
140e0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
140f0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
14100 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
14110 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14120 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14130 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14140 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14150 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14160 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14170 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
14180 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
14190 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
141a0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
141b0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
141c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
141d0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
141e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
141f0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14200 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14210 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14220 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14230 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14240 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
14250 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14260 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14270 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14290 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
142a0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
142b0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
142c0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
142d0 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
142e0 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
142f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14300 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
14310 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
14320 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
14330 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
14340 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
14350 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
14360 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
14370 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
14380 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
14390 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
143a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
143b0 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
143c0 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
143d0 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
143e0 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
143f0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
14400 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
14410 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14420 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
14430 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
14440 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
14450 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
14460 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
14470 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
14480 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14490 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
144a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
144b0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
144c0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
144d0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
144e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
144f0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14500 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
14510 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14520 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14530 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
14540 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
14550 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
14560 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
14570 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
14580 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
14590 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
145a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
145b0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
145c0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
145d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
145e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
145f0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
14600 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14610 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14620 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14630 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14640 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
14650 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14660 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
14670 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
14680 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14690 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
146a0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
146b0 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
146c0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
146d0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
146e0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
146f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14700 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
14710 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14720 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
14730 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14740 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14750 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
14760 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
14770 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
14780 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
14790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
147a0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
147b0 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
147c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
147d0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
147e0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
147f0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
14800 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
14810 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
14820 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
14830 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
14840 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
14850 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
14860 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
14870 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
14880 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
14890 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
148a0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
148b0 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
148c0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
148d0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
148e0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
148f0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
14900 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
14910 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
14920 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14930 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14940 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
14950 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14960 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14970 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14980 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
14990 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
149a0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
149b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
149c0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
149d0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
149e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
149f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14a00 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
14a10 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
14a20 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
14a30 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14a40 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
14a50 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
14a60 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
14a70 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
14a80 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
14a90 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
14aa0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14ab0 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14ac0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
14ad0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
14ae0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
14af0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
14b00 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
14b10 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14b20 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
14b30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14b40 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
14b50 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
14b60 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
14b70 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
14b80 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
14b90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14ba0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14bb0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
14bc0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
14bd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14be0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
14bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14c00 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
14c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14c20 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14c30 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
14c40 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
14c50 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
14c60 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
14c70 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
14c80 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
14c90 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
14ca0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
14cb0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
14cc0 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
14cd0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14ce0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
14cf0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
14d00 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
14d10 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
14d20 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
14d30 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
14d40 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
14d50 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
14d60 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
14d70 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
14d80 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
14d90 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
14da0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
14db0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
14dc0 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
14dd0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
14de0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
14df0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
14e00 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
14e10 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
14e20 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
14e30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
14e40 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
14e50 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
14e60 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
14e70 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
14e80 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
14e90 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
14ea0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14eb0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
14ec0 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
14ed0 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
14ee0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
14ef0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
14f00 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
14f10 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
14f20 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
14f30 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14f40 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
14f50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14f60 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14f70 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
14f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14f90 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14fa0 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
14fb0 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
14fc0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
14fd0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
14fe0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
14ff0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
15000 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
15010 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15020 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15030 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
15040 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
15050 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
15060 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15070 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
15080 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
15090 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
150a0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
150b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
150c0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
150d0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
150e0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
150f0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
15100 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
15110 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
15120 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
15130 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
15140 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
15150 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
15160 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
15170 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
15180 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
15190 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
151a0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
151b0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
151c0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
151d0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
151e0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
151f0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
15200 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
15210 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
15220 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
15230 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
15240 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
15250 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15260 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
15270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15280 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
15290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
152a0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
152b0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
152c0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
152d0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
152e0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
152f0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
15300 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
15310 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
15320 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
15330 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
15340 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
15350 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15370 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
15380 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15390 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
153a0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
153b0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
153c0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
153d0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
153e0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
153f0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
15400 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
15410 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
15420 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
15430 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
15440 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
15450 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
15460 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
15470 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
15480 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
15490 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
154a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
154b0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
154c0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
154d0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
154e0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
154f0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
15500 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
15510 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15520 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
15530 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15540 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
15550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
15560 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
15570 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15580 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
15590 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
155a0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
155b0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
155c0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
155d0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
155e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
155f0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
15600 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
15610 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
15620 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
15630 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
15640 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
15650 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
15660 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
15670 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15680 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
15690 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
156a0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
156b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
156c0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
156d0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
156e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
156f0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
15700 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
15710 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
15720 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
15730 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
15740 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
15750 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
15760 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
15770 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
15780 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
15790 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
157a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
157b0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
157c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
157d0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
157e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
157f0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
15800 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
15810 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
15820 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
15830 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
15840 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
15850 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
15860 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
15870 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
15880 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
15890 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
158a0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
158b0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
158c0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
158d0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
158e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
158f0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
15900 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
15910 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
15920 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
15930 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
15940 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
15950 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
15960 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15970 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
15980 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
15990 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
159a0 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
159b0 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
159c0 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
159d0 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
159e0 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
159f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
15a00 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
15a10 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
15a20 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
15a30 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
15a40 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
15a50 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
15a60 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
15a70 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
15a80 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
15a90 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15aa0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15ab0 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
15ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15ad0 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
15ae0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
15af0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15b00 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
15b10 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15b20 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
15b30 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
15b40 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
15b50 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
15b60 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
15b70 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
15b80 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
15b90 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15ba0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
15bb0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
15bc0 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
15bd0 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
15be0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
15bf0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
15c00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15c10 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
15c20 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
15c30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15c40 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
15c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15c60 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
15c70 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15c80 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
15c90 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
15ca0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
15cb0 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
15cc0 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
15cd0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15ce0 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
15cf0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
15d00 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
15d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15d20 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
15d30 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
15d40 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
15d50 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
15d60 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
15d70 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
15d80 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
15d90 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
15da0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15db0 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
15dc0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15dd0 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
15de0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15df0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
15e00 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
15e10 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
15e20 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
15e30 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
15e40 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
15e50 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
15e60 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
15e70 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
15e80 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
15e90 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
15ea0 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
15eb0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
15ec0 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
15ed0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
15ee0 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
15ef0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
15f00 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
15f10 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
15f20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
15f30 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
15f40 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
15f50 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
15f60 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
15f70 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
15f80 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
15f90 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
15fa0 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
15fb0 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
15fc0 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
15fd0 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
15fe0 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
15ff0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16000 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16010 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
16020 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
16030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16040 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
16050 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
16060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16070 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
16080 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
16090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
160a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
160b0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
160c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
160d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
160e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
160f0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
16100 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16120 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
16130 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
16140 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16150 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16170 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
16180 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16190 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
161a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
161b0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
161c0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
161d0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
161e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
161f0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
16200 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
16210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16220 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
16230 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
16240 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16250 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16260 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16270 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
16280 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16290 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
162a0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
162b0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
162c0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
162d0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
162e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
162f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
16300 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
16310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16320 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16330 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
16340 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16360 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16370 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16380 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16390 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
163a0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
163b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
163c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
163d0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
163e0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
163f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16400 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
16410 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16420 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
16430 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16440 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
16450 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
16460 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
16470 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16480 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16490 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
164a0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
164b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
164c0 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
164d0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
164e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
164f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
16500 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
16510 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
16520 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
16530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16540 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
16550 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
16560 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
16570 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16580 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
16590 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
165a0 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
165b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
165c0 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
165d0 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
165e0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
165f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16600 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
16610 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
16620 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
16630 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
16640 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
16650 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
16660 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16670 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16680 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16690 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
166a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
166b0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
166c0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
166d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
166e0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
166f0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
16700 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
16710 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
16720 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16730 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
16740 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
16750 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
16760 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
16770 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
16780 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16790 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
167a0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
167b0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
167c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
167d0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
167e0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
167f0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
16800 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
16810 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
16820 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
16830 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
16840 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
16850 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
16860 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16870 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
16880 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16890 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
168a0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
168b0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
168c0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
168d0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
168e0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
168f0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
16900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16910 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
16920 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
16930 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16940 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
16950 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
16960 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
16970 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
16980 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
16990 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
169a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
169b0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
169c0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
169d0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
169e0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
169f0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
16a00 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
16a10 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
16a20 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
16a30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16a40 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
16a50 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
16a60 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
16a70 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16a80 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
16a90 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
16aa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16ab0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
16ac0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
16ad0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
16ae0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
16af0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
16b00 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
16b10 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
16b20 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
16b30 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
16b40 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
16b50 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
16b60 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
16b70 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
16b80 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
16b90 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16ba0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
16bb0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
16bc0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
16bd0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
16be0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
16bf0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
16c00 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
16c10 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
16c20 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
16c30 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
16c40 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
16c50 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
16c60 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
16c70 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
16c80 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
16c90 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
16ca0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
16cb0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
16cc0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
16cd0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
16ce0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
16cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
16d00 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
16d10 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
16d20 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
16d30 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
16d40 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
16d50 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
16d60 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
16d70 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
16d80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
16d90 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
16da0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
16db0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
16dc0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16dd0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
16de0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
16df0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
16e00 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
16e10 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
16e20 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
16e30 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
16e40 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
16e50 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16e60 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16e70 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16e80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
16e90 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
16ea0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
16eb0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
16ec0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
16ed0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
16ee0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
16ef0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
16f00 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
16f10 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
16f20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16f30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16f40 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16f50 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16f60 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16f70 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
16f80 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
16f90 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
16fa0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
16fb0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
16fc0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
16fd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
16fe0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
16ff0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
17000 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
17010 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17020 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17030 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17040 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17050 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17060 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17070 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17080 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
17090 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
170a0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
170b0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
170c0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
170d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
170e0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
170f0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17100 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
17110 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
17120 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
17130 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17140 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17150 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17160 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17170 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17180 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17190 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
171a0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
171b0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
171c0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
171d0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
171e0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
171f0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17200 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17210 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17220 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17230 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17240 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17250 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17260 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17270 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
17280 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
17290 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
172a0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
172b0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
172c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
172d0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
172e0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
172f0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
17300 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
17310 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17320 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
17330 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
17340 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
17350 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
17360 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
17370 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
17380 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
17390 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
173a0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
173b0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
173c0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
173d0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
173e0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
173f0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
17400 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
17410 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
17420 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
17430 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
17440 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
17450 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17460 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
17470 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
17480 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
17490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
174a0 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
174b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
174c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  e3.**.** ^Each e
174d0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c  ntry in most SQL
174e0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65  ite tables (exce
174f0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20  pt for [WITHOUT 
17500 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a  ROWID] tables).*
17510 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  * has a unique 6
17520 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
17530 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
17540 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
17550 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
17560 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
17570 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
17580 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
17590 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
175a0 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
175b0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
175c0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
175d0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
175e0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
175f0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
17600 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
17610 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
17620 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
17630 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
17640 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
17650 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
17660 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
17670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
17680 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17690 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72  d(D) interface r
176a0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
176b0 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f  d] of the .** mo
176c0 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
176d0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
176e0 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
176f0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
17700 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
17710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
17720 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74  .** ^Inserts int
17730 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
17740 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
17750 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49   recorded..** ^I
17760 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
17770 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
17780 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68  owid tables.** h
17790 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
177a0 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  d on the databas
177b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  e connection D, 
177c0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
177d0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
177e0 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65  id(D) returns ze
177f0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  ro..**.** ^(If a
17800 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
17810 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
17820 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b  er or within a [
17830 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
17840 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  * method, then t
17850 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
17860 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
17870 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
17880 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f  ted.** row as lo
17890 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
178a0 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
178b0 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e  le method is run
178c0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
178d0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
178e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
178f0 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20  ethod ends, the 
17900 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a  value returned .
17910 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ** by this routi
17920 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68  ne reverts to wh
17930 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65  at it was before
17940 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17950 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
17960 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e   method began.)^
17970 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
17980 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
17990 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
179a0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
179b0 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
179c0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
179d0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
179e0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
179f0 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
17a00 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
17a10 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
17a20 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
17a30 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
17a40 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
17a50 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
17a60 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
17a70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
17a80 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
17a90 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
17aa0 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
17ab0 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
17ac0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
17ad0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
17ae0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
17af0 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
17b00 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
17b10 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
17b20 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
17b30 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
17b40 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
17b50 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
17b60 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
17b70 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
17b80 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
17b90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
17ba0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
17bb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
17bc0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
17bd0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
17be0 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
17bf0 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
17c00 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
17c10 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
17c20 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
17c30 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
17c40 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
17c50 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
17c60 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
17c70 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
17c80 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
17c90 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
17ca0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
17cb0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
17cc0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
17cd0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
17ce0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
17cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
17d00 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17d10 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
17d20 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
17d30 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
17d40 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
17d50 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
17d60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
17d70 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
17d80 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
17d90 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
17da0 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
17db0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
17dc0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
17dd0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
17de0 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
17df0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
17e00 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17e10 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
17e20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17e30 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
17e40 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17e50 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
17e60 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
17e70 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17e80 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
17e90 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20   rows modified, 
17ea0 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64  inserted or.** d
17eb0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
17ec0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
17ed0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
17ee0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a  DATE or DELETE.*
17ef0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  * statement on t
17f00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17f10 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
17f20 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   by the only par
17f30 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63  ameter..** ^Exec
17f40 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
17f50 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
17f60 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d  ement does not m
17f70 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a  odify the value.
17f80 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ** returned by t
17f90 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
17fa0 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65  .** ^Only change
17fb0 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20  s made directly 
17fc0 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
17fd0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
17fe0 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a  statement are.**
17ff0 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75   considered - au
18000 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
18010 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54  caused by [CREAT
18020 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
18030 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65  gers], .** [fore
18040 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
18050 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   or [REPLACE] co
18060 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
18070 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ion are not coun
18080 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e  ted..** .** Chan
18090 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
180a0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
180b0 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45  ed by .** [INSTE
180c0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20  AD OF trigger | 
180d0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
180e0 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ers] are not cou
180f0 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65  nted. ^The value
18100 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79   .** returned by
18110 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18120 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  () immediately a
18130 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20  fter an INSERT, 
18140 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45  UPDATE or .** DE
18150 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72  LETE statement r
18160 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20  un on a view is 
18170 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c  always zero. Onl
18180 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74  y changes made t
18190 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65  o real .** table
181a0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
181b0 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20  *.** Things are 
181c0 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
181d0 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
181e0 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
181f0 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65  on is.** execute
18200 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65  d while a trigge
18210 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e  r program is run
18220 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68  ning. This may h
18230 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20  appen if the.** 
18240 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65  program uses the
18250 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
18260 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66  function], or if
18270 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c   some other call
18280 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
18290 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33   invokes sqlite3
182a0 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63  _changes() direc
182b0 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79  tly. Essentially
182c0 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
182d0 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65     <li> ^(Before
182e0 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67   entering a trig
182f0 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20  ger program the 
18300 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18310 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69  y.**        sqli
18320 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
18330 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e  nction is saved.
18340 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67   After the trigg
18350 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20  er program .**  
18360 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68        has finish
18370 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ed, the original
18380 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72   value is restor
18390 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c  ed.)^.** .**   <
183a0 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74  li> ^(Within a t
183b0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
183c0 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ach INSERT, UPDA
183d0 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a  TE and DELETE .*
183e0 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65  *        stateme
183f0 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75  nt sets the valu
18400 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
18410 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
18420 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20  .**        upon 
18430 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f  completion as no
18440 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c  rmal. Of course,
18450 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c   this value will
18460 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a   not include .**
18470 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e          any chan
18480 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ges performed by
18490 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61   sub-triggers, a
184a0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  s the sqlite3_ch
184b0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
184c0 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65     value will be
184d0 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f   saved and resto
184e0 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73  red after each s
184f0 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72  ub-trigger has r
18500 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  un.)^.** </ul>.*
18510 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e  * .** ^This mean
18520 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68  s that if the ch
18530 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18540 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72  tion (or similar
18550 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20  ) is used.** by 
18560 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54  the first INSERT
18570 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18580 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18590 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69  hin a trigger, i
185a0 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  t .** returns th
185b0 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77  e value as set w
185c0 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  hen the calling 
185d0 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20  statement began 
185e0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49  executing..** ^I
185f0 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20  f it is used by 
18600 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75  the second or su
18610 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74  bsequent such st
18620 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
18630 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f   trigger .** pro
18640 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20  gram, the value 
18650 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74  returned reflect
18660 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18670 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79  rows modified by
18680 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75   the .** previou
18690 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  s INSERT, UPDATE
186a0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
186b0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
186c0 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
186d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
186e0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
186f0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
18700 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
18710 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
18720 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
18730 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18740 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18750 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18760 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
18770 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
18780 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18790 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
187a0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
187b0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
187c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
187d0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
187e0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
187f0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
18800 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
18810 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18820 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
18830 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
18840 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
18850 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18860 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
18870 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
18880 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
18890 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
188a0 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
188b0 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
188c0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
188d0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
188e0 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
188f0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
18900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
18910 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
18920 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
18930 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
18940 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
18950 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
18960 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
18970 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
18980 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
18990 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
189a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
189b0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
189c0 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
189d0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
189e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
189f0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
18a00 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
18a10 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
18a20 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
18a30 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
18a40 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
18a50 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
18a60 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
18a70 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
18a80 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
18a90 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
18aa0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
18ab0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18ac0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18ad0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
18ae0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
18af0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
18b00 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
18b10 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18b20 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18b30 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18b40 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
18b50 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
18b60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18b70 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
18b80 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18b90 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
18ba0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
18bb0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
18bc0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
18bd0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
18be0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
18bf0 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
18c00 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
18c10 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
18c20 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
18c30 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Query.** METHOD:
18c40 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18c50 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
18c60 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
18c70 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
18c80 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
18c90 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
18ca0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
18cb0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
18cc0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
18cd0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
18ce0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
18cf0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
18d00 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
18d10 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
18d20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
18d30 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
18d40 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
18d50 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
18d60 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
18d70 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
18d80 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
18d90 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
18da0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
18db0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
18dc0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
18dd0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
18de0 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
18df0 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
18e00 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
18e10 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
18e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18e30 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
18e40 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
18e50 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
18e60 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
18e70 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
18e80 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
18e90 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
18ea0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
18eb0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
18ec0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18ed0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
18ee0 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
18ef0 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
18f00 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
18f10 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
18f20 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
18f30 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
18f40 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
18f50 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
18f60 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
18f70 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
18f80 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
18f90 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
18fa0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
18fb0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
18fc0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
18fd0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
18fe0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
18ff0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
19000 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
19010 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
19020 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
19030 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
19040 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19050 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
19060 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
19070 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
19080 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
19090 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
190a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
190b0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
190c0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
190d0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
190e0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
190f0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
19100 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
19110 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
19120 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
19130 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
19140 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
19150 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
19160 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
19170 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
19180 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
19190 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
191a0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
191b0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
191c0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
191d0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
191e0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
191f0 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
19200 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
19210 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
19220 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
19230 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
19240 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
19250 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
19260 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
19270 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
19280 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
19290 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
192a0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
192b0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
192c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
192d0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
192e0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
192f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19300 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
19310 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
19320 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
19330 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
19340 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
19350 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
19360 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
19370 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
19380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19390 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
193a0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
193b0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
193c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
193d0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
193e0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
193f0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
19400 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
19410 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
19420 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
19430 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
19440 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
19450 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
19460 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
19470 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
19480 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
19490 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
194a0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
194b0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
194c0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
194d0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
194e0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
194f0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
19500 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
19510 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
19520 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
19530 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
19540 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
19550 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
19560 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
19570 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
19580 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
19590 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
195a0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
195b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
195c0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
195d0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
195e0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
195f0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
19600 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
19610 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
19620 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
19630 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
19640 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
19650 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
19660 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
19670 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
19680 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
19690 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
196a0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
196b0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
196c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
196d0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
196e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
196f0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
19700 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
19710 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
19720 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
19730 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
19740 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
19750 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
19760 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
19770 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
19780 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
19790 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
197a0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
197b0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
197c0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
197d0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
197e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
197f0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
19800 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
19810 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
19820 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
19830 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
19840 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
19850 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
19860 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
19870 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
19880 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
19890 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
198a0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
198b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
198c0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
198d0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
198e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
198f0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
19900 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
19910 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
19920 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
19930 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
19940 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19950 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
19960 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
19970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
19980 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
19990 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
199a0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
199b0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
199c0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
199d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
199e0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
199f0 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
19a00 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
19a10 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
19a20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
19a30 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
19a40 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
19a50 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
19a60 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
19a70 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
19a80 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
19a90 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
19aa0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19ab0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19ac0 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
19ad0 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
19ae0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
19af0 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
19b00 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
19b10 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
19b20 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
19b30 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
19b40 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
19b50 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
19b60 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
19b70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
19b80 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
19b90 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
19ba0 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
19bb0 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
19bc0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19bd0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
19be0 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
19bf0 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
19c00 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
19c10 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
19c20 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
19c30 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
19c40 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
19c50 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
19c60 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
19c70 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
19c80 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
19c90 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
19ca0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19cb0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
19cc0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
19cd0 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
19ce0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
19cf0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
19d00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19d10 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
19d20 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
19d30 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
19d40 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
19d50 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
19d60 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
19d70 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
19d80 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
19d90 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
19da0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
19db0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
19dc0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
19dd0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19de0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
19df0 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
19e00 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
19e10 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
19e20 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
19e30 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
19e40 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
19e50 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
19e60 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
19e70 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
19e80 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
19e90 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
19ea0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
19eb0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
19ec0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19ed0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
19ee0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
19ef0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
19f00 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19f10 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
19f20 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
19f30 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
19f40 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
19f50 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
19f60 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
19f70 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
19f80 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
19f90 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
19fa0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
19fb0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
19fc0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
19fd0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
19fe0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
19ff0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1a000 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1a010 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
1a020 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1a030 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1a040 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1a050 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1a060 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1a070 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1a080 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1a090 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1a0a0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1a0b0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1a0c0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1a0d0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1a0e0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1a0f0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1a100 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1a110 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1a120 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1a130 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1a140 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1a150 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1a160 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1a170 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1a180 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1a190 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1a1a0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1a1b0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1a1c0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1a1d0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1a1e0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1a1f0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1a200 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1a210 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1a220 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1a230 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1a240 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1a250 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1a260 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1a270 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1a280 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1a290 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1a2a0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1a2b0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1a2c0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1a2d0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1a2e0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1a2f0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1a300 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1a310 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1a320 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1a330 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1a340 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1a350 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1a360 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1a370 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1a380 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1a390 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1a3a0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1a3b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1a3c0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1a3d0 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1a3e0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1a3f0 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1a400 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1a410 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1a420 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1a430 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1a440 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1a450 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1a460 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1a470 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1a480 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1a490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a4a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1a4b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1a4c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1a4d0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1a4e0 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1a4f0 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1a500 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1a510 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1a520 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1a530 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1a540 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1a550 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a560 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1a570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1a580 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1a590 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1a5a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a5b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1a5c0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
1a5d0 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
1a5e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a5f0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
1a600 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meout.** METHOD:
1a610 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1a620 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
1a630 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
1a640 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
1a650 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
1a660 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
1a670 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
1a680 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
1a690 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
1a6a0 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
1a6b0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
1a6c0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
1a6d0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1a6e0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1a6f0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
1a700 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
1a710 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
1a720 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1a730 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
1a740 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
1a750 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
1a760 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
1a770 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
1a780 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
1a790 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
1a7a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1a7b0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
1a7c0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
1a7d0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
1a7e0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
1a7f0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
1a800 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1a810 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1a820 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
1a830 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1a840 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a850 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d  ] at any given m
1a860 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1a870 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1a880 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1a890 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1a8a0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1a8b0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1a8c0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1a8d0 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1a8e0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1a8f0 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  eared.)^.**.** S
1a900 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d  ee also:  [PRAGM
1a910 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a  A busy_timeout].
1a920 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1a930 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
1a940 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
1a950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a960 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
1a970 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
1a980 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48   Queries.** METH
1a990 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a9a0 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
1a9b0 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
1a9c0 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
1a9d0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1a9e0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
1a9f0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
1aa00 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
1aa10 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
1aa20 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
1aa30 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
1aa40 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
1aa50 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
1aa60 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
1aa70 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1aa80 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
1aa90 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
1aaa0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
1aab0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
1aac0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
1aad0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
1aae0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
1aaf0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
1ab00 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
1ab10 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
1ab20 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
1ab30 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
1ab40 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1ab50 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
1ab60 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
1ab70 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
1ab80 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
1ab90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1aba0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
1abb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
1abc0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
1abd0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
1abe0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
1abf0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
1ac00 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1ac10 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
1ac20 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
1ac30 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
1ac40 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
1ac50 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
1ac60 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1ac70 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1ac80 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
1ac90 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
1aca0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
1acb0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
1acc0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
1acd0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
1ace0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
1acf0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
1ad00 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
1ad10 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
1ad20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1ad30 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1ad40 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
1ad50 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1ad60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1ad70 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
1ad80 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
1ad90 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
1ada0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
1adb0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
1adc0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
1add0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
1ade0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
1adf0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1ae00 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
1ae10 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
1ae20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
1ae30 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
1ae40 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
1ae50 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
1ae60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1ae70 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
1ae80 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
1ae90 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
1aea0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1aeb0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1aec0 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
1aed0 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
1aee0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
1aef0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
1af00 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
1af10 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
1af20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
1af30 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
1af40 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
1af50 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1af60 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
1af70 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
1af80 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
1af90 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
1afa0 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
1afb0 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
1afc0 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
1afd0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1afe0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
1aff0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
1b000 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
1b010 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
1b020 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
1b030 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b040 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
1b050 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
1b060 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
1b070 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
1b080 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
1b090 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b0a0 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
1b0b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b0c0 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
1b0d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b0e0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
1b0f0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
1b100 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
1b110 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
1b120 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
1b130 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
1b140 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b150 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
1b160 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b170 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
1b180 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b190 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
1b1a0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
1b1b0 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
1b1c0 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
1b1d0 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1b1e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b1f0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
1b200 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
1b210 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
1b220 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1b230 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
1b240 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
1b250 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
1b260 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
1b270 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
1b280 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
1b290 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
1b2a0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b2b0 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
1b2c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
1b2d0 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
1b2e0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b2f0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
1b300 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
1b310 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
1b320 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
1b330 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
1b340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
1b350 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
1b360 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
1b370 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
1b380 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
1b390 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
1b3a0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
1b3b0 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
1b3c0 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
1b3d0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1b3e0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
1b3f0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1b400 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
1b410 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
1b420 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b430 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1b440 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
1b450 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
1b460 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1b470 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
1b480 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
1b490 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
1b4a0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
1b4b0 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
1b4c0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
1b4d0 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
1b4e0 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
1b4f0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
1b500 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
1b510 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
1b520 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
1b530 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
1b540 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
1b550 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
1b560 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
1b570 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
1b580 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
1b590 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1b5a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
1b5b0 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
1b5c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1b5d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b5e0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1b5f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1b600 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1b610 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1b620 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1b630 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1b640 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1b650 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1b660 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1b670 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1b680 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1b690 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1b6a0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1b6b0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1b6c0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1b6d0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1b6e0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1b6f0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1b700 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1b710 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1b720 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1b730 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
1b740 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1b750 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1b760 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1b770 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1b780 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1b790 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1b7a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b7b0 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1b7c0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1b7d0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1b7e0 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1b7f0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1b800 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1b810 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1b820 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1b830 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1b840 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
1b850 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
1b860 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
1b870 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
1b880 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
1b890 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
1b8a0 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
1b8b0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b8c0 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
1b8d0 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
1b8e0 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
1b8f0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
1b900 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
1b910 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b920 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1b930 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1b940 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1b950 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1b960 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1b970 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1b980 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1b990 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1b9a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1b9b0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1b9c0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1b9d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1b9e0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1b9f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1ba00 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1ba10 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1ba20 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1ba30 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1ba40 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1ba50 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1ba60 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1ba70 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1ba80 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1ba90 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1baa0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1bab0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1bac0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1bad0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1bae0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1baf0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1bb00 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1bb10 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1bb20 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1bb30 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1bb40 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1bb50 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1bb60 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1bb70 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1bb80 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1bb90 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1bba0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1bbb0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1bbc0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1bbd0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1bbe0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1bbf0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1bc00 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1bc10 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1bc20 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1bc30 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1bc40 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1bc50 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1bc60 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1bc70 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1bc80 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1bc90 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1bca0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1bcb0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1bcc0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1bcd0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1bce0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1bcf0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1bd00 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1bd10 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1bd20 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1bd30 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1bd40 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1bd50 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1bd60 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1bd70 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1bd80 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1bd90 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1bda0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1bdb0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1bdc0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1bdd0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1bde0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1bdf0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1be00 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1be10 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1be20 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1be30 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1be40 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1be50 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1be60 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1be70 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1be80 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1be90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1bea0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1beb0 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1bec0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1bed0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1bee0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1bef0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1bf00 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1bf10 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1bf20 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1bf30 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1bf40 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1bf50 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1bf60 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1bf70 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1bf80 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1bf90 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1bfa0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1bfb0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
1bfc0 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
1bfd0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1bfe0 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1bff0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1c000 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1c010 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1c020 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1c030 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1c040 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1c050 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1c060 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1c070 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1c080 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1c090 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1c0a0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1c0b0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1c0c0 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1c0d0 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1c0e0 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1c0f0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1c100 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1c110 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1c120 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1c130 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1c140 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1c150 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1c160 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c170 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1c180 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1c190 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1c1a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c1b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1c1c0 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1c1d0 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1c1e0 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1c1f0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c200 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1c210 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1c220 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1c230 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1c240 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1c250 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1c260 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1c270 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1c280 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1c290 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1c2a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1c2b0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1c2c0 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1c2d0 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1c2e0 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1c2f0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1c300 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1c310 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1c320 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c330 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c340 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c350 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1c360 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1c370 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c380 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1c390 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1c3a0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1c3b0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1c3c0 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1c3d0 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1c3e0 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1c3f0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c400 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1c410 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1c420 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1c430 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1c440 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1c450 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1c460 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1c470 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1c480 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1c490 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1c4a0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1c4b0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1c4c0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1c4d0 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1c4e0 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1c4f0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1c500 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1c510 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1c520 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1c530 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1c540 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1c550 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1c560 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1c570 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1c580 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1c590 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1c5a0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1c5b0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1c5c0 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1c5d0 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1c5e0 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1c5f0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1c600 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1c610 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c620 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1c630 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1c640 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c650 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1c660 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1c670 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1c680 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1c690 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1c6a0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1c6b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c6c0 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1c6d0 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1c6e0 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1c6f0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1c700 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1c710 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1c720 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1c730 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1c740 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
1c750 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1c760 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
1c770 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
1c780 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
1c790 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
1c7a0 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
1c7b0 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
1c7c0 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
1c7d0 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
1c7e0 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
1c7f0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
1c800 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
1c810 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
1c820 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1c830 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
1c840 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
1c850 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
1c860 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
1c870 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
1c880 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
1c890 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
1c8a0 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1c8b0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1c8c0 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1c8d0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1c8e0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1c8f0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1c900 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1c910 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1c920 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1c930 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1c940 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1c950 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1c960 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1c970 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1c980 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1c990 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1c9a0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1c9b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1c9c0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1c9d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1c9e0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c9f0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1ca00 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ca10 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1ca20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1ca30 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1ca40 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1ca50 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1ca60 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1ca70 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1ca80 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1ca90 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1caa0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1cab0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1cac0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1cad0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1cae0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1caf0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1cb00 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1cb10 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1cb20 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1cb30 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1cb40 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1cb50 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1cb60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1cb70 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1cb80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1cb90 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1cba0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1cbb0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1cbc0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1cbd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1cbe0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1cbf0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1cc00 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1cc10 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1cc20 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1cc30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1cc40 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1cc50 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1cc60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1cc70 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1cc80 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1cc90 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1cca0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1ccb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1ccc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1ccd0 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1cce0 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1ccf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1cd00 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1cd10 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1cd20 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1cd30 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1cd40 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1cd50 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1cd60 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1cd70 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1cd80 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1cd90 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1cda0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1cdb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1cdc0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1cdd0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1cde0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1cdf0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1ce00 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1ce10 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1ce20 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1ce30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1ce40 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1ce50 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1ce60 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1ce70 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1ce80 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1ce90 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1cea0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1ceb0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1cec0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1ced0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1cee0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1cef0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1cf00 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1cf10 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1cf20 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1cf30 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1cf40 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1cf50 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1cf60 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1cf70 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1cf80 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1cf90 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1cfa0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1cfb0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1cfc0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1cfd0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1cfe0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1cff0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1d000 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1d010 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1d020 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1d030 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1d040 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1d050 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1d060 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1d070 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d080 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1d090 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1d0a0 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1d0b0 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1d0c0 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1d0d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d0e0 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1d0f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d100 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d110 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1d120 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1d130 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1d140 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1d150 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1d160 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1d170 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1d180 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1d190 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1d1a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d1b0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1d1c0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1d1d0 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1d1e0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1d1f0 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1d200 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1d210 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1d220 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1d230 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1d240 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1d250 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1d260 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1d270 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1d280 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1d290 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d2a0 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1d2b0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1d2c0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1d2d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d2e0 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1d2f0 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1d300 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1d310 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1d320 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1d330 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d340 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1d350 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1d360 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1d370 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1d380 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1d390 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1d3a0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1d3b0 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1d3c0 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1d3d0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1d3e0 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1d3f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1d400 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1d410 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1d420 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1d430 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1d440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d450 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1d460 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1d470 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d480 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1d490 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1d4a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1d4b0 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1d4c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1d4d0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d4e0 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1d4f0 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1d500 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1d510 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1d520 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1d530 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1d540 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1d550 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1d560 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1d570 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1d580 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1d590 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1d5a0 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1d5b0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1d5c0 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1d5d0 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1d5e0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1d5f0 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1d600 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1d610 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1d620 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1d630 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1d640 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1d650 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1d660 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1d670 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1d680 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1d690 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1d6a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d6b0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1d6c0 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1d6d0 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1d6e0 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1d6f0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1d700 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1d710 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1d720 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1d730 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1d740 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1d750 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1d760 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1d770 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1d780 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1d790 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1d7a0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1d7b0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1d7c0 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1d7d0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1d7e0 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1d7f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1d800 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1d810 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1d820 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1d830 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1d840 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1d850 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1d860 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1d870 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1d880 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1d890 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1d8a0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1d8b0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1d8c0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1d8d0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1d8e0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1d8f0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1d900 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1d910 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1d920 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1d930 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1d940 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1d950 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1d960 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1d970 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1d980 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1d990 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1d9a0 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1d9b0 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1d9c0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1d9d0 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1d9e0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1d9f0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1da00 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1da10 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1da20 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1da30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1da40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1da50 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1da60 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1da70 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1da80 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1da90 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1daa0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1dab0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1dac0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1dad0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1dae0 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1daf0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1db00 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1db10 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1db20 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1db30 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1db40 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1db50 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1db60 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1db70 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1db80 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1db90 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1dba0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1dbb0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1dbc0 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1dbd0 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1dbe0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1dbf0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1dc00 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1dc10 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1dc20 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1dc30 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1dc40 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
1dc50 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1dc60 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1dc70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1dc80 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1dc90 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1dca0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1dcb0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1dcc0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1dcd0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1dce0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1dcf0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1dd00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1dd10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1dd20 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1dd30 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1dd40 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1dd50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1dd60 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1dd70 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1dd80 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1dd90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1dda0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1ddb0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1ddc0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1ddd0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1dde0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1ddf0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1de00 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1de10 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1de20 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1de30 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1de40 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1de50 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1de60 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1de70 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1de80 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1de90 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1dea0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1deb0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1dec0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1ded0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1dee0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1def0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1df00 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1df10 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1df20 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1df30 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1df40 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1df50 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1df60 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1df70 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1df80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1df90 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1dfa0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1dfb0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1dfc0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1dfd0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1dfe0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1dff0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1e000 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1e010 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1e020 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e030 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1e040 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1e050 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1e060 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e070 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1e080 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1e090 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1e0a0 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1e0b0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1e0c0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1e0d0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1e0e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e0f0 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1e100 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1e110 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1e120 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1e130 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1e140 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1e150 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1e160 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1e170 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1e180 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1e190 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1e1a0 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1e1b0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1e1c0 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1e1d0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1e1e0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1e1f0 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1e200 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1e210 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1e220 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1e230 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1e240 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1e250 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1e260 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1e270 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1e280 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1e290 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1e2a0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1e2b0 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1e2c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1e2d0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1e2e0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1e2f0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
1e300 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
1e310 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
1e320 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
1e330 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
1e340 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
1e350 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
1e360 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
1e370 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
1e380 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
1e390 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
1e3a0 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
1e3b0 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
1e3c0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1e3d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
1e3e0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1e3f0 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
1e400 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1e410 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1e420 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
1e430 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1e440 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
1e450 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
1e460 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
1e470 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
1e480 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1e490 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1e4a0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1e4b0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1e4c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1e4d0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1e4e0 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
1e4f0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1e500 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1e510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e520 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1e530 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1e540 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
1e550 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1e560 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1e570 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1e580 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e590 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1e5a0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1e5b0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1e5c0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1e5d0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1e5e0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1e5f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1e600 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1e610 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1e620 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1e630 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1e640 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1e650 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1e660 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1e670 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1e680 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e690 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1e6a0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1e6b0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1e6c0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1e6d0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1e6e0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1e6f0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1e700 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1e710 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e720 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1e730 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1e740 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1e750 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1e760 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e770 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1e780 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1e790 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1e7a0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1e7b0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1e7c0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1e7d0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1e7e0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1e7f0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1e800 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1e810 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1e820 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1e830 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1e840 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1e850 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1e860 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1e870 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e880 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1e890 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1e8a0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1e8b0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1e8c0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1e8d0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1e8e0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1e8f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1e900 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1e910 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1e920 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1e930 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1e940 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1e950 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1e960 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1e970 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1e980 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1e990 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1e9a0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1e9b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1e9c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1e9d0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1e9e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e9f0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1ea00 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1ea10 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1ea20 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1ea30 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1ea40 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1ea50 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1ea60 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1ea70 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1ea80 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1ea90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1eaa0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1eab0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1eac0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1ead0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1eae0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1eaf0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1eb00 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1eb10 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1eb20 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1eb30 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1eb40 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1eb50 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1eb60 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1eb70 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1eb80 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1eb90 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1eba0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1ebb0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1ebc0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1ebd0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1ebe0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1ebf0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1ec00 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1ec10 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1ec20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1ec30 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1ec40 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1ec50 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1ec60 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1ec70 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1ec80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1ec90 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1eca0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1ecb0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1ecc0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1ecd0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1ece0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1ecf0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1ed00 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1ed10 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1ed20 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1ed30 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1ed40 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1ed50 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1ed60 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1ed70 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1ed80 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1ed90 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1eda0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1edb0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1edc0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1edd0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1ede0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1edf0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1ee00 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1ee10 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1ee20 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1ee30 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1ee40 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1ee50 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1ee60 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1ee70 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1ee80 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1ee90 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1eea0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1eeb0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1eec0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1eed0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1eee0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1eef0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1ef00 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1ef10 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1ef20 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1ef30 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1ef40 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1ef50 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1ef60 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1ef70 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1ef80 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1ef90 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1efa0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1efb0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1efc0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1efd0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1efe0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1eff0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1f000 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1f010 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1f020 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1f030 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1f040 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1f050 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1f060 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1f070 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1f080 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1f090 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1f0a0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1f0b0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1f0c0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1f0d0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1f0e0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1f0f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1f100 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1f110 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1f120 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1f130 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1f140 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1f150 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1f160 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1f170 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1f180 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1f190 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1f1a0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1f1b0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1f1c0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1f1d0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1f1e0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1f1f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1f200 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1f210 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1f220 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1f230 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1f240 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1f250 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1f260 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1f270 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1f280 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1f290 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1f2a0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1f2b0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1f2c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1f2d0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1f2e0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1f2f0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1f300 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f310 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1f320 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1f330 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1f340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f350 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1f360 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f370 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1f380 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1f390 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1f3a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f3b0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1f3c0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1f3d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1f3e0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1f3f0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1f400 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1f410 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1f420 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1f430 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1f440 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1f450 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1f460 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1f470 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1f480 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1f490 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1f4a0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1f4b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1f4c0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1f4d0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1f4e0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1f4f0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1f500 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1f510 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1f520 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1f530 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1f540 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1f550 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1f560 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1f570 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1f580 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1f590 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1f5a0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1f5b0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1f5c0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1f5d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1f5e0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1f5f0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1f600 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1f610 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1f620 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1f630 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1f640 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1f650 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1f660 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1f670 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1f680 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1f690 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1f6a0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1f6b0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1f6c0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1f6d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1f6e0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1f6f0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1f700 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1f710 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1f720 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1f730 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f740 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1f750 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f760 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1f770 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1f780 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1f790 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1f7a0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1f7b0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1f7c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1f7d0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1f7e0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1f7f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1f800 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1f810 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1f820 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1f830 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1f840 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1f850 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1f860 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1f870 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
1f880 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
1f890 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
1f8a0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1f8b0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1f8c0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1f8d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f8e0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1f8f0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1f900 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1f910 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1f920 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1f930 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1f940 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1f950 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1f960 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1f970 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1f980 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1f990 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1f9a0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f9b0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1f9c0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1f9d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1f9e0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1f9f0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1fa00 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1fa10 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1fa20 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1fa30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1fa40 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1fa50 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1fa60 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1fa70 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1fa80 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1fa90 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1faa0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1fab0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1fac0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1fad0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1fae0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1faf0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1fb00 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1fb10 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1fb20 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1fb30 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1fb40 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1fb50 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1fb60 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1fb70 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1fb80 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1fb90 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1fba0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1fbb0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1fbc0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1fbd0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1fbe0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1fbf0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1fc00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1fc10 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1fc20 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1fc30 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1fc40 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1fc50 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1fc60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1fc70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fc80 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1fc90 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1fca0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1fcb0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1fcc0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1fcd0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1fce0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1fcf0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1fd00 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1fd10 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1fd20 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1fd30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fd40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fd50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1fd60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1fd70 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1fd80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fd90 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1fda0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1fdb0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1fdc0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fdd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fde0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1fdf0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1fe00 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1fe10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fe20 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fe30 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1fe40 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1fe50 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1fe60 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1fe70 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fe80 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1fe90 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1fea0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1feb0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1fec0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1fed0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1fee0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1fef0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1ff00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ff10 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ff20 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1ff30 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ff40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ff50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ff60 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1ff70 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1ff80 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ff90 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ffa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ffb0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1ffc0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1ffd0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ffe0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fff0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20000 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
20010 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
20020 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20030 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20040 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20050 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
20060 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
20070 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20080 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20090 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
200a0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
200b0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
200c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
200d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
200e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
200f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
20100 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
20110 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
20120 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20140 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
20150 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
20160 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20170 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20190 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
201a0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
201b0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
201c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
201d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
201e0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
201f0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
20200 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
20210 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20230 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
20240 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
20250 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
20260 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20280 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
20290 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
202a0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
202b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
202c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
202d0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
202e0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
202f0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20300 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20310 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
20320 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
20330 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
20340 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
20350 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
20360 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
20370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20380 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
20390 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
203a0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
203b0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
203c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
203d0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
203e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
203f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20400 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
20410 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
20420 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
20430 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20440 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20450 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
20460 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
20470 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20480 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
20490 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
204a0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
204b0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
204c0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
204d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
204e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
204f0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
20500 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
20510 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
20520 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20530 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20540 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
20550 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
20560 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
20570 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20590 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
205a0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
205b0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
205c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
205d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
205e0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
205f0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
20600 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20610 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20620 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20630 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
20640 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
20650 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
20660 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
20670 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20680 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
20690 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
206a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
206b0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
206c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
206d0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
206e0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
206f0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
20700 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
20710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
20720 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
20730 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
20740 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
20750 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
20760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
20770 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
20780 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
20790 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
207a0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
207b0 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
207c0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
207d0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
207e0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
207f0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
20800 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
20810 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
20820 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
20830 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20840 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
20850 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
20860 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
20870 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
20880 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
20890 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
208a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
208b0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
208c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
208d0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
208e0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
208f0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
20900 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
20910 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
20920 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
20930 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
20940 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20950 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
20960 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
20970 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
20980 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
20990 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
209a0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
209b0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
209c0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
209d0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
209e0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
209f0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
20a00 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
20a10 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
20a20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
20a30 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
20a40 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
20a50 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
20a60 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
20a70 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
20a80 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
20a90 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
20aa0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
20ab0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
20ac0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
20ad0 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
20ae0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
20af0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
20b00 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
20b10 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20b20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
20b30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
20b40 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
20b50 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
20b60 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
20b70 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
20b80 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
20b90 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20ba0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
20bb0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
20bc0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
20bd0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
20be0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
20bf0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
20c00 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
20c10 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
20c20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
20c30 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
20c40 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
20c50 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
20c60 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
20c70 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
20c80 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
20c90 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
20ca0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
20cb0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
20cc0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
20cd0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
20ce0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
20cf0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
20d00 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
20d10 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
20d20 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
20d30 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
20d40 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
20d50 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
20d60 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
20d70 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
20d80 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
20d90 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
20da0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20db0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
20dc0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
20dd0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
20de0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
20df0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
20e00 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
20e10 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
20e20 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
20e30 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
20e40 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
20e50 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
20e60 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
20e70 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
20e80 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
20e90 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
20ea0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
20eb0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
20ec0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
20ed0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
20ee0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
20ef0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
20f00 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
20f10 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
20f20 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
20f30 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
20f40 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
20f50 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
20f60 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
20f70 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
20f80 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
20f90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20fa0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
20fb0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
20fc0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
20fd0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
20fe0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
20ff0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
21000 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
21010 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
21020 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
21030 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
21040 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21050 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
21060 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
21070 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
21080 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
21090 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
210a0 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
210b0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
210c0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
210d0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
210e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
210f0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
21100 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
21110 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
21120 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
21130 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
21140 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
21150 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
21160 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
21170 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
21180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21190 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
211a0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
211b0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
211c0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
211d0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
211e0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
211f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
21200 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
21210 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
21220 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
21230 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
21240 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
21250 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
21260 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
21270 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
21280 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
21290 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
212a0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
212b0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
212c0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
212d0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
212e0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
212f0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
21300 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
21310 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
21320 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
21330 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
21340 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
21350 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21360 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
21370 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
21380 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
21390 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
213a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
213b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
213c0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
213d0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
213e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
213f0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
21400 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
21410 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
21420 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
21430 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
21440 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
21450 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
21460 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
21470 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
21480 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
21490 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
214a0 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
214b0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
214c0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
214d0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
214e0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
214f0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
21500 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21510 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
21520 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
21530 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
21540 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
21550 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21560 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
21570 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
21580 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
21590 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
215a0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
215b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
215c0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
215d0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
215e0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
215f0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
21600 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
21610 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
21620 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
21630 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
21640 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
21650 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
21660 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
21670 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
21680 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
21690 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
216a0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
216b0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
216c0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
216d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
216e0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
216f0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
21700 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
21710 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
21720 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
21730 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21740 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
21750 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
21760 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
21770 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
21780 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
21790 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
217a0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
217b0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
217c0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
217d0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
217e0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
217f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21800 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
21810 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
21820 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
21830 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
21840 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
21850 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21860 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21870 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
21880 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
21890 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
218a0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
218b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
218c0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
218d0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
218e0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
218f0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
21900 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
21910 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
21920 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
21930 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
21940 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21950 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
21960 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
21970 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
21980 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
21990 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
219a0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
219b0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
219c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
219d0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
219e0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
219f0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
21a00 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
21a10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
21a20 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
21a30 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
21a40 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
21a50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21a60 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
21a70 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
21a80 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
21a90 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
21aa0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
21ab0 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
21ac0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
21ad0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
21ae0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
21af0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
21b00 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
21b10 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
21b20 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
21b30 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21b40 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
21b50 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
21b60 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
21b70 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
21b80 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
21b90 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
21ba0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21bb0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
21bc0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
21bd0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
21be0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
21bf0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
21c00 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
21c10 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
21c20 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21c30 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
21c40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
21c50 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21c60 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
21c70 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
21c80 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
21c90 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
21ca0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
21cb0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
21cc0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
21cd0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
21ce0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
21cf0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
21d00 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
21d10 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
21d20 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
21d30 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21d40 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
21d50 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
21d60 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
21d70 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
21d80 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21d90 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
21da0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
21db0 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
21dc0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
21dd0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
21de0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
21df0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
21e00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
21e10 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
21e20 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
21e30 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
21e40 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
21e50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21e60 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
21e70 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
21e80 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
21e90 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
21ea0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
21eb0 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
21ec0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
21ed0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
21ee0 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
21ef0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
21f00 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
21f10 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21f20 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
21f30 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
21f40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21f50 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
21f60 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
21f70 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
21f80 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
21f90 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
21fa0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
21fb0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
21fc0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
21fd0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
21fe0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
21ff0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
22000 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
22010 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22020 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
22030 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
22040 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
22050 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
22060 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
22070 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
22080 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
22090 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
220a0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
220b0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
220c0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
220d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
220e0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
220f0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
22100 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
22110 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
22120 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
22130 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
22140 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
22150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
22160 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
22170 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
22180 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22190 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
221a0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
221b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
221c0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
221d0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
221e0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
221f0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
22200 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
22210 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
22220 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22230 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22240 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22250 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
22260 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
22270 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
22280 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
22290 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
222a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
222b0 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
222c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
222d0 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
222e0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
222f0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
22300 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
22310 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
22320 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
22330 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
22340 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
22350 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
22360 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
22370 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
22380 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
22390 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
223a0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
223b0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
223c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
223d0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
223e0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
223f0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
22400 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
22410 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
22420 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
22430 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
22440 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
22450 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
22460 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
22470 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
22480 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
22490 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
224a0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
224b0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
224c0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
224d0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
224e0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
224f0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
22500 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
22510 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
22520 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
22530 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
22540 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
22550 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
22560 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
22570 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
22580 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
22590 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
225a0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
225b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
225c0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
225d0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
225e0 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
225f0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
22600 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
22610 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
22620 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
22630 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
22640 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
22650 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
22660 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
22670 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
22680 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
22690 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
226a0 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
226b0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
226c0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
226d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
226e0 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
226f0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
22700 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
22710 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
22720 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
22730 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
22740 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
22750 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
22760 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
22770 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
22780 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
22790 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
227a0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
227b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
227c0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
227d0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
227e0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
227f0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
22800 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
22810 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
22820 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
22830 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
22840 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
22850 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
22860 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
22870 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
22880 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
22890 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
228a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
228b0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
228c0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
228d0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
228e0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
228f0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
22900 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
22910 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
22920 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
22930 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
22940 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
22950 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
22960 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22970 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
22980 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
22990 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
229a0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
229b0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
229c0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
229d0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
229e0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
229f0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
22a00 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
22a10 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
22a20 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
22a30 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
22a40 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
22a50 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
22a60 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
22a70 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
22a80 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
22a90 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
22aa0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
22ab0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
22ac0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
22ad0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
22ae0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
22af0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
22b00 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
22b10 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
22b20 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
22b30 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
22b40 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
22b50 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
22b60 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
22b70 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
22b80 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
22b90 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
22ba0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
22bb0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
22bc0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
22bd0 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
22be0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
22bf0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
22c00 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
22c10 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
22c20 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
22c30 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
22c40 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
22c50 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
22c60 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
22c70 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
22c80 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
22c90 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
22ca0 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
22cb0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
22cc0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
22cd0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
22ce0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
22cf0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
22d00 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
22d10 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
22d20 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
22d30 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
22d40 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
22d50 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
22d60 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
22d70 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
22d80 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
22d90 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
22da0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
22db0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
22dc0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
22dd0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
22de0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
22df0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
22e00 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
22e10 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
22e20 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
22e30 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
22e40 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
22e50 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
22e60 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
22e70 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
22e80 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
22e90 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
22ea0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
22eb0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
22ec0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22ed0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
22ee0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
22ef0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
22f00 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
22f10 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
22f20 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
22f30 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
22f40 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
22f50 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
22f60 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
22f70 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
22f80 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
22f90 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
22fa0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
22fb0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22fc0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
22fd0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
22fe0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
22ff0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
23000 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
23010 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
23020 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
23030 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
23040 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
23050 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
23060 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
23070 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
23080 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
23090 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
230a0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
230b0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
230c0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
230d0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
230e0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
230f0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
23100 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
23110 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
23120 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
23130 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
23140 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23150 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
23160 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
23170 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
23180 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
23190 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
231a0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
231b0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
231c0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
231d0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
231e0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
231f0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
23200 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
23210 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
23220 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
23230 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
23240 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
23250 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
23260 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
23270 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
23280 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23290 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
232a0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
232b0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
232c0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
232d0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
232e0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
232f0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
23300 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
23310 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
23320 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
23330 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
23340 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
23350 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
23360 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
23370 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
23380 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
23390 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
233a0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
233b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
233c0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
233d0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
233e0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
233f0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
23400 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
23410 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
23420 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
23430 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
23440 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
23450 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
23460 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
23470 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
23480 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
23490 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
234a0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
234b0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
234c0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
234d0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
234e0 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
234f0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
23500 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
23510 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
23520 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
23530 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
23540 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
23550 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
23560 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
23570 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
23580 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
23590 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
235a0 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
235b0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
235c0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
235d0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
235e0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
235f0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
23600 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
23610 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
23620 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
23630 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
23640 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
23650 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
23660 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
23670 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
23680 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
23690 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
236a0 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
236b0 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
236c0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
236d0 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
236e0 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
236f0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
23700 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
23710 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
23720 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
23730 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
23740 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
23750 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
23760 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
23770 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
23780 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
23790 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
237a0 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
237b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
237c0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
237d0 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
237e0 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
237f0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
23800 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
23810 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
23820 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
23830 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
23840 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
23850 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
23860 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
23870 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
23880 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
23890 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
238a0 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
238b0 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
238c0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
238d0 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
238e0 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
238f0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
23900 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
23910 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
23920 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
23930 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
23940 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
23950 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
23960 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
23970 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
23980 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
23990 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
239a0 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
239b0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
239c0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
239d0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
239e0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
239f0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
23a00 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
23a10 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
23a20 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
23a30 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
23a40 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
23a50 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
23a60 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
23a70 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
23a80 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
23a90 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
23aa0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
23ab0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
23ac0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
23ad0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
23ae0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
23af0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
23b00 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
23b10 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
23b20 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
23b30 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
23b40 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
23b50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23b60 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
23b70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23b80 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
23b90 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
23ba0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
23bb0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
23bc0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23bd0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
23be0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
23bf0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
23c00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
23c10 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
23c20 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23c30 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
23c40 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
23c50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
23c60 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23c70 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
23c80 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
23c90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23ca0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
23cb0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
23cc0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
23cd0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
23ce0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
23cf0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
23d00 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
23d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
23d20 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
23d30 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
23d40 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
23d50 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
23d60 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
23d70 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
23d80 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
23d90 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
23da0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
23db0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
23dc0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
23dd0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
23de0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
23df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
23e00 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
23e10 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
23e20 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
23e30 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
23e40 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
23e50 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
23e60 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
23e70 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
23e80 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
23e90 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
23ea0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
23eb0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
23ec0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
23ed0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
23ee0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
23ef0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
23f00 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
23f10 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
23f20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
23f30 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
23f40 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
23f50 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
23f60 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
23f70 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
23f80 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
23f90 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
23fa0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
23fb0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
23fc0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
23fd0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
23fe0 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
23ff0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
24000 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
24010 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
24020 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
24030 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
24040 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
24050 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
24060 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
24070 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
24080 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
24090 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
240a0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
240b0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
240c0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
240d0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
240e0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
240f0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
24100 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
24110 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
24120 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
24130 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
24140 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
24150 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
24160 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
24170 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
24180 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
24190 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
241a0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
241b0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
241c0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
241d0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
241e0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
241f0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
24200 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
24210 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
24220 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
24230 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
24240 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
24250 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
24260 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
24270 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
24280 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
24290 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
242a0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
242b0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
242c0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
242d0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
242e0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
242f0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
24300 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
24310 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
24320 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
24330 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
24340 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
24350 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
24360 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
24370 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
24380 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
24390 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
243a0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
243b0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
243c0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
243d0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
243e0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
243f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
24400 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
24410 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
24420 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
24430 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
24440 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
24450 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
24460 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
24470 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
24480 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24490 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
244a0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
244b0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
244c0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
244d0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
244e0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
244f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
24500 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
24510 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
24520 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
24530 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
24540 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24550 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
24560 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
24570 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
24580 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
24590 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
245a0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
245b0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
245c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
245d0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
245e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
245f0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
24600 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
24610 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
24620 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24630 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
24640 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
24650 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24660 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
24670 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
24680 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
24690 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
246a0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
246b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
246c0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
246d0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
246e0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
246f0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
24700 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
24710 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
24720 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
24730 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
24740 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
24750 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
24760 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
24770 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
24780 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
24790 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
247a0 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
247b0 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
247c0 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
247d0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
247e0 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
247f0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
24800 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
24810 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
24820 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24830 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
24840 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
24850 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
24860 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
24870 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
24880 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
24890 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
248a0 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
248b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
248c0 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
248d0 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
248e0 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
248f0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
24900 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
24910 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
24920 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24930 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
24940 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
24950 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
24960 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
24970 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
24980 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
24990 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
249a0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
249b0 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
249c0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
249d0 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
249e0 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
249f0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24a00 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24a10 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
24a20 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
24a30 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
24a40 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24a50 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
24a60 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
24a70 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
24a80 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
24a90 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
24aa0 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
24ab0 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
24ac0 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
24ad0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
24ae0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
24af0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
24b00 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
24b10 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
24b20 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
24b30 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
24b40 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
24b50 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
24b60 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
24b70 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
24b80 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
24b90 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
24ba0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
24bb0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
24bc0 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
24bd0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
24be0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
24bf0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
24c00 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
24c10 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
24c20 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
24c30 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
24c40 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
24c50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
24c60 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
24c70 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
24c80 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
24c90 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
24ca0 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
24cb0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
24cc0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
24cd0 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
24ce0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24cf0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
24d00 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
24d10 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
24d20 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
24d30 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
24d40 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
24d50 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
24d60 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
24d70 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
24d80 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
24d90 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
24da0 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
24db0 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
24dc0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
24dd0 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
24de0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
24df0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24e00 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
24e10 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
24e20 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24e30 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
24e40 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
24e50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
24e60 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
24e70 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
24e80 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
24e90 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
24ea0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
24eb0 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
24ec0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24ed0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
24ee0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
24ef0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
24f00 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
24f10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24f20 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
24f30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
24f40 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
24f50 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
24f60 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24f70 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
24f80 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
24f90 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
24fa0 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
24fb0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
24fc0 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
24fd0 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
24fe0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
24ff0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
25000 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
25010 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
25020 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
25030 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
25040 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74  ost recent sqlit
25050 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
25060 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
25070 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
25080 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64  ection] D failed
25090 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
250a0 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e  e3_errcode(D) in
250b0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
250c0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
250d0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
250e0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
250f0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a   code] for that.
25100 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20  ** API call..** 
25110 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
25120 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20  nt API call was 
25130 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74  successful,.** t
25140 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
25150 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
25160 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
25170 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68  ndefined..** ^Th
25180 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
25190 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
251a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
251b0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
251c0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
251d0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
251e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
251f0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
25200 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
25210 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
25220 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
25230 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
25240 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
25250 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
25260 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
25270 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
25280 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
25290 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
252a0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
252b0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
252c0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
252d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
252e0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
252f0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
25300 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
25310 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
25320 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
25330 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
25340 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
25350 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
25360 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
25370 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
25380 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
25390 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
253a0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
253b0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
253c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
253d0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
253e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
253f0 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
25400 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
25410 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
25420 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
25430 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
25440 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
25450 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
25460 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
25470 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
25480 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
25490 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
254a0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
254b0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
254c0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
254d0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
254e0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
254f0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
25500 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
25510 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
25520 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
25530 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
25540 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
25550 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
25560 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
25570 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
25580 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
25590 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
255a0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
255b0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
255c0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
255d0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
255e0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
255f0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
25600 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
25610 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
25620 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
25630 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25640 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
25650 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
25660 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
25670 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
25680 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
25690 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
256a0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
256b0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
256c0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
256d0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
256e0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
256f0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
25700 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
25710 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
25720 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
25730 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
25740 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
25750 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
25760 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
25770 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
25780 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
25790 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
257a0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
257b0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
257c0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
257d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
257e0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
257f0 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
25800 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
25810 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
25820 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25830 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
25840 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
25850 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
25860 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
25870 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25880 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
25890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
258a0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
258b0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
258c0 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
258d0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
258e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
258f0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
25900 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
25910 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
25920 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
25930 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61  ement that.** ha
25940 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20  s been compiled 
25950 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d  into binary form
25960 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f   and is ready to
25970 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a   be evaluated..*
25980 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61  *.** Think of ea
25990 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
259a0 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63   as a separate c
259b0 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e  omputer program.
259c0 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61    The.** origina
259d0 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f  l SQL text is so
259e0 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72  urce code.  A pr
259f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25a00 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74   object .** is t
25a10 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65  he compiled obje
25a20 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51  ct code.  All SQ
25a30 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  L must be conver
25a40 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72  ted into a.** pr
25a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25a60 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62   before it can b
25a70 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  e run..**.** The
25a80 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61   life-cycle of a
25a90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25aa0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c  ent object usual
25ab0 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69  ly goes like thi
25ac0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
25ad0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
25ae0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25af0 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  ent object using
25b00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25b10 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e  e_v2()]..** <li>
25b20 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
25b30 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69  [parameters] usi
25b40 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
25b50 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
25b60 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
25b70 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
25b80 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
25b90 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
25ba0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
25bb0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
25bc0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25bd0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
25be0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
25bf0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
25c00 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
25c10 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
25c20 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
25c30 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
25c40 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
25c50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
25c60 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65  ** </ol>.*/.type
25c70 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
25c80 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
25c90 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
25ca0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
25cb0 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44  Limits.** METHOD
25cc0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
25cd0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
25ce0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
25cf0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
25d00 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
25d10 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
25d20 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
25d30 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
25d40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
25d50 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
25d60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25d70 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
25d80 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
25d90 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
25da0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
25db0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
25dc0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
25dd0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
25de0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
25df0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
25e00 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
25e10 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
25e20 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
25e30 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
25e40 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
25e50 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
25e60 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
25e70 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
25e80 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
25e90 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
25ea0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
25eb0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
25ec0 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
25ed0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
25ee0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
25ef0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
25f00 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
25f10 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
25f20 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
25f30 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
25f40 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
25f50 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
25f60 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
25f70 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
25f80 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
25f90 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
25fa0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
25fb0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25fc0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
25fd0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
25fe0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
25ff0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
26000 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
26010 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
26020 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
26030 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
26040 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
26050 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
26060 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
26070 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
26080 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
26090 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
260a0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
260b0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
260c0 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
260d0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
260e0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
260f0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
26100 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
26110 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
26120 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
26130 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
26140 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
26150 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
26160 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
26170 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
26180 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
26190 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
261a0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
261b0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
261c0 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
261d0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
261e0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
261f0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
26200 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
26210 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
26220 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
26230 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
26240 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
26250 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
26260 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
26270 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
26280 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
26290 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
262a0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
262b0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
262c0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
262d0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
262e0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
262f0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
26300 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
26310 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
26320 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
26330 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
26340 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
26350 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
26360 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
26370 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
26380 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
26390 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
263a0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
263b0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
263c0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
263d0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
263e0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
263f0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
26400 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
26410 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
26420 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
26430 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
26440 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
26450 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
26460 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
26470 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
26480 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
26490 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
264a0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
264b0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
264c0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
264d0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
264e0 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
264f0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
26500 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
26510 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
26520 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
26530 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
26540 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
26550 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
26560 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
26570 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
26580 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
26590 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
265a0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
265b0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
265c0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
265d0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
265e0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
265f0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
26600 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26610 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
26620 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
26630 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26640 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
26650 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
26660 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
26670 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
26680 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
26690 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
266a0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
266b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
266c0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
266d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
266e0 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
266f0 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
26700 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
26710 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26720 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
26730 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
26740 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
26750 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26760 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26770 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
26780 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
26790 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
267a0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
267b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
267c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
267d0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
267e0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
267f0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
26800 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26810 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
26820 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
26830 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
26840 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
26850 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
26860 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
26870 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
26880 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
26890 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
268a0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
268b0 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
268c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
268d0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
268e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
268f0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
26900 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
26910 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
26920 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
26930 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
26940 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
26950 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
26960 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
26970 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26980 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
26990 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
269a0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
269b0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
269c0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
269d0 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
269e0 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
269f0 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
26a00 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
26a10 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
26a20 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
26a30 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
26a40 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26a50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
26a60 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
26a70 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
26a80 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
26a90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26aa0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
26ab0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
26ac0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
26ad0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26ae0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
26af0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26b00 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
26b10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26b20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
26b30 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
26b40 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
26b50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
26b60 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
26b70 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
26b80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26b90 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
26ba0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
26bb0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
26bc0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
26bd0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
26be0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
26bf0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
26c00 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
26c10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26c20 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
26c30 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
26c40 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
26c50 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
26c60 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26c70 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
26c80 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
26c90 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
26ca0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
26cb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
26cc0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
26cd0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
26ce0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
26cf0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26d00 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
26d10 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
26d20 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
26d30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26d40 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
26d50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26d60 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
26d70 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
26d80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26d90 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
26da0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
26db0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
26dc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26dd0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
26de0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
26df0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
26e00 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
26e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26e20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
26e30 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
26e40 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
26e50 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
26e60 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
26e70 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
26e80 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
26e90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
26ea0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
26eb0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
26ec0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
26ed0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
26ee0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
26ef0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
26f00 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
26f10 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
26f20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
26f30 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
26f40 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
26f50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26f60 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
26f70 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
26f80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26f90 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
26fa0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
26fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26fc0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
26fd0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
26fe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26ff0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
27000 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
27010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27020 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
27030 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
27040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27050 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
27060 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
27070 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
27080 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
27090 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
270a0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
270b0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
270c0 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
270d0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
270e0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
270f0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
27100 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
27110 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
27120 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
27130 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
27140 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
27150 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
27160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
27170 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
27180 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
27190 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
271a0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
271b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
271c0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
271d0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
271e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
271f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
27200 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
27210 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
27220 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
27230 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
27240 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
27250 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
27260 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
27270 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
27280 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
27290 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
272a0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
272b0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
272c0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
272d0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
272e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
272f0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
27300 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
27310 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
27320 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
27330 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
27340 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
27350 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
27360 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
27370 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
27380 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
27390 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
273a0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
273b0 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
273c0 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
273d0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
273e0 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
273f0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
27400 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
27410 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
27420 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
27430 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
27440 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
27450 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
27460 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
27470 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
27480 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
27490 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
274a0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
274b0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
274c0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
274d0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
274e0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
274f0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
27500 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
27510 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
27520 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
27530 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
27540 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
27550 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
27560 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
27570 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
27580 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
27590 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
275a0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
275b0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
275c0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
275d0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
275e0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
275f0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
27600 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27610 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
27620 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
27630 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
27640 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
27650 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
27660 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
27670 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
27680 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
27690 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
276a0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
276b0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
276c0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
276d0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
276e0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
276f0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
27700 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
27710 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
27720 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
27730 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
27740 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
27750 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
27760 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
27770 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
27780 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
27790 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
277a0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
277b0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
277c0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
277d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
277e0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
277f0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
27800 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
27810 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
27820 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
27830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27840 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
27850 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
27860 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
27870 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
27880 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
27890 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
278a0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
278b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
278c0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
278d0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
278e0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
278f0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
27900 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27910 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
27920 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
27930 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
27940 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
27950 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
27960 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
27970 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
27980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
27990 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
279a0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
279b0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
279c0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
279d0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
279e0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
279f0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
27a00 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
27a10 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
27a20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
27a30 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
27a40 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
27a50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
27a60 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
27a70 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
27a80 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
27a90 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
27aa0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
27ab0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
27ac0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
27ad0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
27ae0 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
27af0 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
27b00 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
27b10 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
27b20 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
27b30 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
27b40 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
27b50 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
27b60 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
27b70 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
27b80 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
27b90 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
27ba0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
27bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27bc0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
27bd0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
27be0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
27bf0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
27c00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27c10 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
27c20 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
27c30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
27c40 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
27c50 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
27c60 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
27c70 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
27c80 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
27c90 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
27ca0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
27cb0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
27cc0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
27cd0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
27ce0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
27cf0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
27d00 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
27d10 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
27d20 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
27d30 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
27d40 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
27d50 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
27d60 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
27d70 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
27d80 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
27d90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
27da0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
27db0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
27dc0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
27dd0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
27de0 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
27df0 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
27e00 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
27e10 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
27e20 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
27e30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
27e40 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
27e50 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
27e60 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
27e70 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
27e80 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
27e90 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
27ea0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
27eb0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
27ec0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
27ed0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
27ee0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
27ef0 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
27f00 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
27f10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
27f20 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
27f30 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
27f40 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
27f50 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
27f60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
27f70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
27f80 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
27f90 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
27fa0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
27fb0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
27fc0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
27fd0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27fe0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
27ff0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
28000 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
28010 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
28020 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28030 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28040 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28050 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28060 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28070 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28080 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28090 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
280a0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
280b0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
280c0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
280d0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
280e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
280f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
28100 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
28110 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
28120 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
28130 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
28140 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
28150 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
28160 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
28170 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
28180 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
28190 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
281a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
281b0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
281c0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
281d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
281e0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
281f0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
28200 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
28210 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
28220 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
28230 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
28240 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28250 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28260 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
28270 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
28280 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
28290 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
282a0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
282b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
282c0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
282d0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
282e0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
282f0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
28300 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
28310 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28320 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
28330 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
28340 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
28350 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
28360 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
28370 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
28380 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28390 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
283a0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
283b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
283c0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
283d0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
283e0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
283f0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28400 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28410 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28420 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28430 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28440 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28450 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28460 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28470 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28480 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28490 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
284a0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
284b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
284c0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
284d0 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
284e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
284f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
28500 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
28510 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
28520 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
28530 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
28540 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
28550 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
28560 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
28570 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
28580 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
28590 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
285a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
285b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
285c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
285d0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
285e0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
285f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
28600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28610 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
28620 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
28630 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
28640 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ase.** METHOD: s
28650 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
28660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
28670 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
28680 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28690 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
286a0 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
286b0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
286c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
286d0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
286e0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
286f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
28700 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
28710 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
28720 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28730 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
28740 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
28750 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
28760 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
28770 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
28780 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
28790 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
287a0 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
287b0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
287c0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
287d0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
287e0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
287f0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
28800 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
28810 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
28820 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
28830 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
28840 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
28850 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
28860 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
28870 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
28880 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
28890 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
288a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
288b0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
288c0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
288d0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
288e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
288f0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
28900 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28910 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
28920 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
28930 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
28940 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
28950 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
28960 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
28970 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
28980 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
28990 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
289a0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
289b0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
289c0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
289d0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
289e0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
289f0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
28a00 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
28a10 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
28a20 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
28a30 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
28a40 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
28a50 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
28a60 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
28a70 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
28a80 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
28a90 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
28aa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28ab0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
28ac0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
28ad0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
28ae0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
28af0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
28b00 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
28b10 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
28b20 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
28b30 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
28b40 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
28b50 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
28b60 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
28b70 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
28b80 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
28b90 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
28ba0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
28bb0 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
28bc0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
28bd0 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d   Been Reset.** M
28be0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
28bf0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
28c00 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
28c10 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
28c20 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
28c30 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
28c40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c50 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
28c60 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
28c70 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
28c80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
28c90 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65  ] but has neithe
28ca0 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  r run to complet
28cb0 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a  ion (returned.**
28cc0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66   [SQLITE_DONE] f
28cd0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rom [sqlite3_ste
28ce0 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65  p(S)]) nor.** be
28cf0 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
28d00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
28d10 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
28d20 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
28d30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28d40 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
28d50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
28d60 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
28d70 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
28d80 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
28d90 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
28da0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28db0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
28dc0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
28dd0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
28de0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
28df0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
28e00 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
28e10 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
28e20 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
28e30 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
28e40 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
28e50 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28e60 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
28e70 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
28e80 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
28e90 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
28ea0 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
28eb0 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
28ec0 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
28ed0 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
28ee0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
28ef0 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
28f00 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
28f10 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
28f20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
28f30 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  pen..*/.int sqli
28f40 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71  te3_stmt_busy(sq
28f50 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
28f60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28f70 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
28f80 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
28f90 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
28fa0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28fb0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
28fc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
28fd0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
28fe0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
28ff0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
29000 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
29010 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
29020 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
29030 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
29040 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
29050 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
29060 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
29070 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
29080 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
29090 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
290a0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
290b0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
290c0 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
290d0 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
290e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
290f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29100 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
29110 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
29120 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
29130 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
29140 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
29150 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29160 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
29170 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
29180 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
29190 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
291a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
291b0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
291c0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
291d0 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
291e0 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
291f0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
29200 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
29210 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
29220 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29230 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ue.  The.** [sql
29240 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29  ite3_value_dup()
29250 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ] interface can 
29260 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74  be used to const
29270 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70  ruct a new .** p
29280 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29290 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75  _value from an u
292a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
292b0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
292c0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
292d0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
292e0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
292f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
29300 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
29310 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
29320 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
29330 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
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 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
29360 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
29370 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
29380 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
29390 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
293a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
293b0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
293c0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
293d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
293e0 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
293f0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
29400 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
29410 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
29420 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
29430 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
29440 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
29450 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
29460 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
29470 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
29480 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
29490 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
294a0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
294b0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
294c0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
294d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
294e0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
294f0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
29500 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
29510 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
29520 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
29530 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
29540 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
29550 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
29560 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
29570 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
29580 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
29590 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
295a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
295b0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
295c0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
295d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
295e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
295f0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
29600 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
29610 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
29620 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
29630 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29640 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
29650 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
29660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
29670 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
29680 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
29690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
296a0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
296b0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
296c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
296d0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
296e0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
296f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
29700 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
29710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
29720 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
29730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
29740 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
29750 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
29760 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
29770 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
29780 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29790 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
297a0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
297b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
297c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
297d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
297e0 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
297f0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
29800 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
29810 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
29820 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
29830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
29840 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
29850 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
29860 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
29870 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
29880 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
29890 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
298a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
298b0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
298c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
298d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
298e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
298f0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
29900 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
29910 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
29920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
29930 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
29940 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
29950 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29960 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
29970 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
29980 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
29990 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
299a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
299b0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
299c0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
299d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
299e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
299f0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
29a00 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
29a10 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
29a20 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
29a30 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
29a40 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
29a50 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
29a60 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
29a70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
29a80 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
29a90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
29aa0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
29ab0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
29ac0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
29ad0 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  g}.** METHOD: sq
29ae0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
29af0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
29b00 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
29b10 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
29b20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
29b30 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
29b40 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
29b50 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
29b60 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
29b70 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
29b80 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
29b90 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
29ba0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
29bb0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
29bc0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
29bd0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
29be0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
29bf0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
29c00 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
29c10 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
29c20 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
29c30 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
29c40 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
29c50 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
29c60 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
29c70 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
29c80 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
29c90 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
29ca0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
29cb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
29cc0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
29cd0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
29ce0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29cf0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
29d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
29d10 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
29d20 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29d30 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
29d40 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
29d50 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
29d60 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
29d70 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
29d80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29d90 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
29da0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
29db0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
29dc0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
29dd0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
29de0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
29df0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
29e00 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
29e10 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
29e20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
29e30 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
29e40 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
29e50 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
29e60 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
29e70 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
29e80 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
29e90 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
29ea0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
29eb0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
29ec0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
29ed0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
29ee0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
29ef0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
29f00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29f10 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
29f20 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
29f30 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
29f40 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
29f50 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
29f60 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
29f70 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
29f80 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
29f90 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
29fa0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
29fb0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
29fc0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
29fd0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
29fe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
29ff0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2a000 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
2a010 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
2a020 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2a030 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2a040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a050 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a060 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
2a070 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
2a080 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
2a090 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
2a0a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2a0b0 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
2a0c0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
2a0d0 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
2a0e0 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
2a0f0 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
2a100 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
2a110 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
2a120 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
2a130 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
2a140 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2a150 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
2a160 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
2a170 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
2a180 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a190 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
2a1a0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
2a1b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2a1c0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
2a1d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2a1e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a1f0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2a200 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a210 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
2a220 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2a230 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
2a240 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
2a250 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
2a260 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2a270 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2a280 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
2a290 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a2a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a2b0 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
2a2c0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
2a2d0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2a2e0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
2a2f0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
2a300 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
2a310 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
2a320 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
2a330 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a340 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
2a350 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2a360 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
2a370 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2a380 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2a390 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2a3a0 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2a3b0 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2a3c0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2a3d0 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2a3e0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2a3f0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2a400 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2a410 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2a420 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2a430 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a440 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2a450 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2a460 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2a470 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2a480 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2a490 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2a4a0 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2a4b0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2a4c0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2a4d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2a4e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2a4f0 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
2a500 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
2a510 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
2a520 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
2a530 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2a540 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
2a550 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
2a560 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2a570 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
2a580 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
2a590 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2a5a0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2a5b0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2a5c0 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
2a5d0 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
2a5e0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2a5f0 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2a600 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2a610 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2a620 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2a630 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2a640 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2a650 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2a660 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2a670 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2a680 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2a690 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2a6a0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2a6b0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2a6c0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2a6d0 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2a6e0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2a6f0 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2a700 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2a710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a720 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2a730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2a740 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2a750 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a760 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2a770 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2a780 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2a790 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2a7a0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2a7b0 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2a7c0 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2a7d0 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2a7e0 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2a7f0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2a800 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2a810 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2a820 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2a830 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2a840 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2a850 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2a860 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2a870 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2a880 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2a890 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2a8a0 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2a8b0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2a8c0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2a8d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2a8e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a8f0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2a900 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2a910 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2a920 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2a930 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2a940 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2a950 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2a960 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2a970 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2a980 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2a990 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2a9a0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2a9b0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2a9c0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2a9d0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2a9e0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2a9f0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2aa00 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2aa10 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2aa20 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2aa30 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2aa40 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2aa50 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2aa60 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2aa70 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2aa80 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2aa90 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2aaa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2aab0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2aac0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2aad0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2aae0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2aaf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2ab00 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2ab10 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2ab20 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2ab30 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2ab40 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2ab50 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2ab60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2ab70 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2ab80 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2ab90 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2aba0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2abb0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2abc0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2abd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2abe0 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2abf0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2ac00 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2ac10 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2ac20 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2ac30 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2ac40 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2ac50 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2ac60 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2ac70 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2ac80 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2ac90 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2aca0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2acb0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2acc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2acd0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2ace0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2acf0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2ad00 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2ad10 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
2ad20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2ad30 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
2ad40 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2ad50 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
2ad60 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2ad70 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2ad80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2ad90 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2ada0 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2adb0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2adc0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2add0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2ade0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2adf0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2ae00 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2ae10 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2ae20 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2ae30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2ae40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ae50 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2ae60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ae70 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2ae80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2ae90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2aea0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2aeb0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2aec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2aed0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2aee0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2aef0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2af00 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2af10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2af20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2af30 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2af40 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2af50 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2af60 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2af70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2af80 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2af90 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2afa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2afb0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2afc0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
2afd0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2afe0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2aff0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2b000 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
2b010 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2b020 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b030 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2b040 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2b050 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2b060 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2b070 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2b080 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2b090 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2b0a0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b0b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2b0c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2b0d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2b0e0 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2b0f0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2b100 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2b110 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2b120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2b130 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2b140 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2b150 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69  oding);.int sqli
2b160 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2b170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b180 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2b190 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2b1a0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2b1b0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2b1c0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2b1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b1e0 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69  _zeroblob64(sqli
2b1f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b200 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
2b210 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b220 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2b230 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
2b240 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2b250 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
2b260 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2b270 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2b280 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2b290 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2b2a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b2b0 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2b2c0 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2b2d0 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2b2e0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2b2f0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2b300 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2b310 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2b320 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2b330 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2b340 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2b350 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2b360 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2b370 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2b380 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2b390 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2b3a0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2b3b0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2b3c0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2b3d0 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2b3e0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2b3f0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2b400 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2b410 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2b420 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2b430 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2b440 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2b450 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2b460 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2b470 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2b480 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b490 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2b4a0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2b4b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b4c0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2b4d0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2b4e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b4f0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2b500 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b510 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2b520 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b540 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2b550 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
2b560 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2b570 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2b580 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b590 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2b5a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2b5b0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2b5c0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2b5d0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2b5e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b5f0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2b600 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2b610 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2b620 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2b630 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2b640 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2b650 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2b660 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2b670 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2b680 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2b690 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2b6a0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2b6b0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2b6c0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2b6d0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2b6e0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2b6f0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2b700 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2b710 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2b720 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2b730 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2b740 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2b750 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2b760 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2b770 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2b780 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2b790 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2b7a0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2b7b0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2b7c0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2b7d0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2b7e0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2b7f0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2b800 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2b810 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2b820 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2b830 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2b840 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2b850 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2b860 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2b870 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2b880 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2b890 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2b8a0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2b8b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b8c0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2b8d0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b8e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2b8f0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2b900 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b910 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2b920 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2b930 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b940 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2b950 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b960 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b970 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2b980 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2b990 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2b9a0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2b9b0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2b9c0 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2b9d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b9e0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2b9f0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2ba00 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2ba10 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2ba20 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2ba30 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2ba40 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2ba50 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2ba60 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2ba70 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2ba80 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2ba90 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2baa0 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2bab0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2bac0 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2bad0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2bae0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2baf0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2bb00 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2bb10 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2bb20 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2bb30 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2bb40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2bb50 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2bb60 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2bb70 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2bb80 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2bb90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bba0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2bbb0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2bbc0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2bbd0 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
2bbe0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bbf0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2bc00 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2bc10 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2bc20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2bc30 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2bc40 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2bc50 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
2bc60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2bc70 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
2bc80 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2bc90 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2bca0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2bcb0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2bcc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2bcd0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2bce0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2bcf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2bd00 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2bd10 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2bd20 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2bd30 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
2bd40 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2bd50 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2bd60 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2bd70 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2bd80 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2bd90 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2bda0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2bdb0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2bdc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2bdd0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2bde0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2bdf0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2be00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2be10 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2be20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2be30 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2be40 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2be50 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2be60 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2be70 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2be80 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2be90 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2bea0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2beb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2bec0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2bed0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2bee0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2bef0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2bf00 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2bf10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2bf20 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2bf30 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2bf40 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2bf50 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2bf60 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2bf70 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2bf80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2bf90 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2bfa0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2bfb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2bfc0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2bfd0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2bfe0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2bff0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2c000 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2c010 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c020 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2c030 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2c040 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2c050 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2c060 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c070 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2c080 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2c090 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c0a0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2c0b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c0c0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2c0d0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2c0e0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2c0f0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2c100 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2c110 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2c120 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2c130 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c140 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2c150 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2c160 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c170 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2c180 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2c190 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2c1a0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2c1b0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2c1c0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2c1d0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2c1e0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2c1f0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2c200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c210 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2c220 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2c230 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2c240 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2c250 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2c260 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2c270 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2c280 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2c290 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2c2a0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2c2b0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2c2c0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2c2d0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2c2e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2c2f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2c300 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2c310 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2c320 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2c330 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2c340 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2c350 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2c360 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2c370 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2c380 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c390 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2c3a0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2c3b0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2c3c0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2c3d0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2c3e0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2c3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c400 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c410 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
2c420 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c430 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2c440 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2c450 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c460 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2c470 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2c480 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
2c490 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c4a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c4b0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2c4c0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2c4d0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2c4e0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2c4f0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2c500 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2c510 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2c520 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2c530 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c540 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2c550 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2c560 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2c570 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2c580 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2c590 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2c5a0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2c5b0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2c5c0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2c5d0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2c5e0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2c5f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2c600 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2c610 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2c620 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c630 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2c640 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2c650 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2c660 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2c670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c680 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2c690 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2c6a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2c6b0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2c6c0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2c6d0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2c6e0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2c6f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c700 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2c710 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2c720 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2c730 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2c740 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2c750 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2c760 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2c770 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2c780 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2c790 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2c7a0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2c7b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2c7c0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2c7d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2c7e0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2c7f0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2c800 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2c810 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2c820 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2c830 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2c840 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2c850 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2c860 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2c870 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2c880 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2c890 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2c8a0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2c8b0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2c8c0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2c8d0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2c8e0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2c8f0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2c900 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2c910 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2c920 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2c930 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2c940 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2c950 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2c960 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2c970 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2c980 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2c990 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2c9a0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2c9b0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2c9c0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2c9d0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2c9e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2c9f0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2ca00 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2ca10 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2ca20 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2ca30 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2ca40 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2ca50 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2ca60 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2ca70 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2ca80 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2ca90 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2caa0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2cab0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2cac0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2cad0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2cae0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2caf0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2cb00 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2cb10 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2cb20 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2cb30 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2cb40 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2cb50 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2cb60 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2cb70 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2cb80 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2cb90 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2cba0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2cbb0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2cbc0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2cbd0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2cbe0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2cbf0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2cc00 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2cc10 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2cc20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2cc30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2cc40 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2cc50 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2cc60 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2cc70 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2cc80 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2cc90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2cca0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2ccb0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2ccc0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2ccd0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2cce0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ccf0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
2cd00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2cd10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2cd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2cd30 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2cd40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2cd50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2cd60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2cd70 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2cd80 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2cd90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2cda0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2cdb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2cdc0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2cdd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2cde0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2cdf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2ce00 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2ce10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2ce20 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2ce30 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2ce40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ce50 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2ce60 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2ce70 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2ce80 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ce90 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2cea0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2ceb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cec0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2ced0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2cee0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2cef0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2cf00 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2cf10 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2cf20 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2cf30 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2cf40 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2cf50 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2cf60 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2cf70 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2cf80 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2cf90 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2cfa0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2cfb0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2cfc0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2cfd0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2cfe0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2cff0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2d000 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2d010 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2d020 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2d030 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2d040 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2d050 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2d060 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2d070 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2d080 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2d090 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2d0a0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2d0b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2d0c0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2d0d0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2d0e0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2d0f0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2d100 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2d110 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2d120 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2d130 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2d140 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2d150 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2d160 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2d170 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2d180 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2d190 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2d1a0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2d1b0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2d1c0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2d1d0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2d1e0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2d1f0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2d200 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2d210 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2d220 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2d230 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2d240 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2d250 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2d260 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2d270 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2d280 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2d290 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2d2a0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2d2b0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2d2c0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2d2d0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2d2e0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
2d2f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2d300 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2d310 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2d320 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d330 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2d340 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2d350 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2d360 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2d370 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2d380 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2d390 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d3a0 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2d3b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2d3c0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2d3d0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2d3e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d3f0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2d400 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d410 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2d420 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2d430 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2d440 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2d450 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d460 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2d470 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2d480 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2d490 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2d4a0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2d4b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2d4c0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2d4d0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2d4e0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2d4f0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2d500 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2d510 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2d520 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2d530 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2d540 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2d550 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2d560 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d570 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2d580 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2d590 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2d5a0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2d5b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2d5c0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2d5d0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2d5e0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2d5f0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2d600 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2d610 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2d620 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2d630 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2d640 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2d650 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2d660 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2d670 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2d680 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2d690 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2d6a0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2d6b0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2d6c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2d6d0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d6e0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2d6f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2d700 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2d710 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
2d720 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
2d730 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
2d740 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
2d750 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
2d760 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
2d770 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
2d780 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2d790 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2d7a0 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2d7b0 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2d7c0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2d7d0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2d7e0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2d7f0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2d800 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2d810 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2d820 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2d830 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2d840 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2d850 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2d860 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2d870 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2d880 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2d890 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2d8a0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2d8b0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2d8c0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2d8d0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2d8e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2d8f0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2d900 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2d910 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2d920 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2d930 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2d940 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2d950 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2d960 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2d970 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2d980 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2d990 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2d9a0 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2d9b0 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2d9c0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2d9d0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2d9e0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2d9f0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2da00 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2da10 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2da20 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2da30 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2da40 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2da50 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2da60 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2da70 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2da80 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2da90 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2daa0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2dab0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2dac0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2dad0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2dae0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2daf0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2db00 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2db10 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2db20 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2db30 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2db40 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2db50 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2db60 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2db70 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2db80 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2db90 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2dba0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2dbb0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2dbc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2dbd0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2dbe0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2dbf0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2dc00 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2dc10 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2dc20 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2dc30 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2dc40 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2dc50 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2dc60 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2dc70 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2dc80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2dc90 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2dca0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2dcb0 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2dcc0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2dcd0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2dce0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2dcf0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2dd00 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2dd10 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2dd20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2dd30 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2dd40 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2dd50 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2dd60 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2dd70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2dd80 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2dd90 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2dda0 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2ddb0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2ddc0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2ddd0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2dde0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2ddf0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2de00 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2de10 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2de20 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2de30 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2de40 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2de50 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2de60 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2de70 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2de80 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2de90 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2dea0 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2deb0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2dec0 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2ded0 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2dee0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2def0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2df00 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2df10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2df20 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2df30 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2df40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2df50 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2df60 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2df70 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2df80 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2df90 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2dfa0 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2dfb0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2dfc0 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2dfd0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2dfe0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2dff0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2e000 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2e010 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2e020 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2e030 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2e040 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2e050 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2e060 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2e070 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2e080 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2e090 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2e0a0 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2e0b0 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2e0c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2e0d0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2e0e0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2e0f0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2e100 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2e110 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2e120 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2e130 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2e140 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2e150 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2e160 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2e170 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2e180 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2e190 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2e1a0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2e1b0 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2e1c0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2e1d0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2e1e0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2e1f0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2e200 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2e210 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2e220 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2e230 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2e240 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2e250 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2e260 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2e270 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2e280 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2e290 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e2a0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2e2b0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2e2c0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2e2d0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2e2e0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2e2f0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2e300 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2e310 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2e320 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2e330 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2e340 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2e350 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2e360 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2e370 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2e380 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2e390 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2e3a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2e3b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e3c0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2e3d0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2e3e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e3f0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2e400 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2e410 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2e420 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2e430 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2e440 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2e450 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2e460 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2e470 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2e480 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2e490 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2e4a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
2e4b0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2e4c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e4d0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2e4e0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2e4f0 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
2e500 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e510 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e520 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
2e530 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e540 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2e550 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
2e560 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2e570 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2e580 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e590 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
2e5a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e5b0 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
2e5c0 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
2e5d0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
2e5e0 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
2e5f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e600 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
2e610 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
2e620 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
2e630 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2e640 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
2e650 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2e660 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2e670 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
2e680 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
2e690 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2e6a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2e6b0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2e6c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2e6d0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
2e6e0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e6f0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2e700 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
2e710 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
2e720 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
2e730 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
2e740 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
2e750 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
2e760 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2e770 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2e780 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
2e790 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
2e7a0 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
2e7b0 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
2e7c0 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
2e7d0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
2e7e0 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
2e7f0 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
2e800 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
2e810 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
2e820 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
2e830 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2e840 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2e850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
2e860 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2e870 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2e880 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e890 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2e8a0 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2e8b0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2e8c0 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2e8d0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2e8e0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2e8f0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2e900 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2e910 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2e920 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2e930 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2e940 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2e950 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2e960 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2e970 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2e980 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2e990 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2e9a0 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2e9b0 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2e9c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2e9d0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2e9e0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2e9f0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2ea00 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2ea10 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2ea20 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2ea30 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2ea40 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2ea50 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2ea60 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2ea70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2ea80 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2ea90 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2eaa0 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2eab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2eac0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2ead0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2eae0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2eaf0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2eb00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2eb10 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2eb20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2eb30 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2eb40 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2eb50 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2eb60 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2eb70 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2eb80 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2eb90 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2eba0 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2ebb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2ebc0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2ebd0 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
2ebe0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ebf0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2ec00 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2ec10 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2ec20 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2ec30 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2ec40 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2ec50 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2ec60 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2ec70 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2ec80 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2ec90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eca0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2ecb0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2ecc0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2ecd0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2ece0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2ecf0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ed00 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2ed10 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2ed20 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2ed30 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2ed40 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2ed50 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2ed60 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2ed70 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2ed80 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2ed90 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2eda0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2edb0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2edc0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2edd0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2ede0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2edf0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2ee00 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2ee10 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2ee20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2ee30 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2ee40 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2ee50 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2ee60 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2ee70 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2ee80 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2ee90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2eea0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2eeb0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2eec0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2eed0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2eee0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2eef0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2ef00 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2ef10 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2ef20 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2ef30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ef40 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2ef50 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2ef60 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2ef70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ef80 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2ef90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2efa0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2efb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2efc0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2efd0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2efe0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2eff0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2f000 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2f010 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2f020 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2f030 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2f040 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f050 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2f060 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2f070 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2f080 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2f090 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2f0a0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2f0b0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2f0c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2f0d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2f0e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2f0f0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2f100 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2f110 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2f120 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2f130 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2f140 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2f150 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2f160 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2f170 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2f180 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2f190 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2f1a0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2f1b0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2f1c0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2f1d0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2f1e0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2f1f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f200 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2f210 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2f220 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2f230 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2f240 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2f250 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2f260 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2f270 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2f280 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2f290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f2a0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2f2b0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2f2c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2f2d0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2f2e0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2f2f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2f300 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2f310 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2f320 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2f330 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2f340 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2f350 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2f360 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2f370 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2f380 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f390 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2f3a0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2f3b0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f3c0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2f3d0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2f3e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f3f0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2f400 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2f410 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2f420 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f430 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2f440 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2f450 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2f460 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f470 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2f480 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2f490 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2f4a0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2f4b0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2f4c0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2f4d0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f4e0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2f4f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f500 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2f510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f520 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2f530 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2f540 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2f550 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2f560 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2f570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f580 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2f590 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2f5a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2f5b0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2f5c0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2f5d0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2f5e0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2f5f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f600 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2f610 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2f620 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2f630 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2f640 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2f650 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f660 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2f670 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2f680 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f690 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2f6a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2f6b0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2f6c0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2f6d0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2f6e0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2f6f0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2f700 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2f710 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f720 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2f730 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f740 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2f750 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2f760 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2f770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f780 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2f790 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f7a0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2f7b0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2f7c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2f7d0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2f7e0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2f7f0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2f800 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2f810 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2f820 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2f830 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2f840 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2f850 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2f860 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2f870 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2f880 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2f890 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2f8a0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2f8b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f8c0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2f8d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f8e0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2f8f0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2f900 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2f910 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2f920 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2f930 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2f940 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2f950 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2f960 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2f970 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
2f980 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
2f990 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2f9a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f9b0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2f9c0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2f9d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f9e0 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
2f9f0 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
2fa00 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
2fa10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2fa20 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2fa30 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2fa40 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
2fa50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2fa60 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2fa70 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2fa80 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2fa90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2faa0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2fab0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2fac0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2fad0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2fae0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2faf0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2fb00 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2fb10 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2fb20 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2fb30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fb40 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2fb50 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2fb60 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
2fb70 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
2fb80 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  afe..**.** These
2fb90 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2fba0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2fbb0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2fbc0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2fbd0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2fbe0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2fbf0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2fc00 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2fc10 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2fc20 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2fc30 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2fc40 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2fc50 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2fc60 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2fc70 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2fc80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2fc90 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2fca0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2fcb0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2fcc0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2fcd0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2fce0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2fcf0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2fd00 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2fd10 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2fd20 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2fd30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2fd40 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2fd50 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2fd60 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2fd70 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2fd80 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2fd90 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2fda0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2fdb0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2fdc0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
2fdd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2fde0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2fdf0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2fe00 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2fe10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2fe20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2fe30 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
2fe40 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2fe50 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
2fe60 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2fe70 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2fe80 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2fe90 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2fea0 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
2feb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2fec0 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
2fed0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2fee0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
2fef0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2ff00 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2ff10 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2ff20 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2ff30 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2ff40 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2ff50 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2ff60 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
2ff70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2ff80 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
2ff90 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2ffa0 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
2ffb0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2ffc0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2ffd0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
2ffe0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
2fff0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
30000 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
30010 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
30020 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30030 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
30040 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
30050 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
30060 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30070 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30080 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
30090 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
300a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
300b0 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
300c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
300d0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
300e0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
300f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
30100 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
30110 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
30120 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  uote>)^.**.** No
30130 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
30140 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
30150 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
30160 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
30170 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
30180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30190 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
301a0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
301b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
301c0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
301d0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
301e0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
301f0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
30200 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
30210 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
30220 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
30230 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
30240 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
30250 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
30260 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
30270 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30280 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30290 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
302a0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
302b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
302c0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
302d0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
302e0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
302f0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
30300 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
30310 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
30320 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30330 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
30340 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
30350 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
30360 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
30370 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
30380 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
30390 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
303a0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
303b0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
303c0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
303d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
303e0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
303f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30400 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
30410 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
30420 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
30430 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
30440 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
30450 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
30460 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
30470 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
30480 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
30490 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
304a0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
304b0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
304c0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
304d0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
304e0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
304f0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
30500 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
30510 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
30520 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
30530 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
30540 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
30550 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
30560 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
30570 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
30580 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
30590 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
305a0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
305b0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
305c0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
305d0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f  ** The safest po
305e0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
305f0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
30600 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
30610 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
30620 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
30630 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
30640 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
30650 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
30660 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
30670 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
30680 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30690 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
306a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
306b0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
306c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
306d0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
306e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
306f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
30700 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
30710 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
30720 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
30730 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
30740 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
30750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30760 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
30770 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
30780 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
30790 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
307a0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
307b0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
307c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
307d0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
307e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
307f0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
30800 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
30810 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
30820 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
30830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30840 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
30850 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
30860 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
30870 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30880 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
30890 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
308a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
308b0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
308c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
308d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
308e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
308f0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
30900 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
30910 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
30920 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
30930 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
30940 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
30950 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
30960 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
30970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
30980 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
30990 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
309a0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
309b0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
309c0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
309d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
309e0 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e   Do <em>not</em>
309f0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
30a00 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
30a10 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
30a20 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
30a30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30a40 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
30a50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
30a60 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
30a70 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
30a80 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
30a90 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
30aa0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
30ab0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
30ac0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
30ad0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
30ae0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
30af0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
30b00 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
30b10 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
30b20 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
30b30 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
30b40 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
30b50 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
30b60 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
30b70 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
30b80 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
30b90 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
30ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
30bb0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
30bc0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
30bd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30be0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
30bf0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
30c00 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
30c10 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
30c20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30c30 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
30c40 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
30c50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30c60 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
30c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
30c80 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30c90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
30ca0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
30cb0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
30cc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30cd0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
30ce0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
30cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30d00 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30d10 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
30d20 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30d30 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
30d40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30d50 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
30d60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
30d70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30d80 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
30d90 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
30da0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
30db0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30dc0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
30dd0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
30de0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
30df0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
30e00 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
30e10 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
30e20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
30e30 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
30e40 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
30e50 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
30e60 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
30e70 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
30e80 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
30e90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
30ea0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
30eb0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
30ec0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
30ed0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
30ee0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
30ef0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
30f00 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
30f10 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
30f20 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
30f30 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
30f40 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
30f50 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
30f60 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
30f70 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
30f80 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
30f90 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
30fa0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
30fb0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
30fc0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
30fd0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
30fe0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
30ff0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
31000 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
31010 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
31020 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
31030 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
31040 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
31050 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
31060 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
31070 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
31080 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
31090 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
310a0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
310b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
310c0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
310d0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
310e0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
310f0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
31100 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
31110 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
31120 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
31130 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
31140 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
31150 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
31160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31170 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
31180 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
31190 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
311a0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
311b0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
311c0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
311d0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
311e0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
311f0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
31200 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
31210 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
31220 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
31230 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
31240 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
31250 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
31260 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
31270 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
31280 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
31290 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
312a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
312b0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
312c0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
312d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
312e0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
312f0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
31300 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31310 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
31320 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
31330 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
31340 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
31350 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31360 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
31370 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
31380 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
31390 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
313a0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
313b0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
313c0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
313d0 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
313e0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
313f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
31400 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
31410 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
31420 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
31430 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
31440 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
31450 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
31460 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
31470 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
31480 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
31490 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
314a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
314b0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
314c0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
314d0 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
314e0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
314f0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
31500 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
31510 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
31520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31530 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
31540 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
31550 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
31560 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
31570 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
31580 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
31590 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
315a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
315b0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
315c0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
315d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
315e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
315f0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
31600 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
31610 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
31620 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
31630 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
31640 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
31650 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
31660 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
31670 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
31680 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
31690 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
316a0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
316b0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
316c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
316d0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
316e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
316f0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
31700 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
31710 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31720 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
31730 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
31740 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
31750 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
31760 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
31770 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
31780 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
31790 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
317a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
317b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
317c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
317d0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
317e0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
317f0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
31800 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
31810 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
31820 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
31830 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
31840 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
31850 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
31860 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
31870 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
31880 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
31890 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
318a0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
318b0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
318c0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
318d0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
318e0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
318f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
31900 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
31910 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
31920 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
31930 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
31940 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
31950 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
31960 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
31970 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
31980 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
31990 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
319a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
319b0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
319c0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
319d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
319e0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
319f0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
31a00 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
31a10 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
31a20 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
31a30 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
31a40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
31a50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31a60 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
31a70 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
31a80 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
31a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31aa0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
31ab0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
31ac0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
31ad0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
31ae0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
31af0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
31b00 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
31b10 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
31b20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
31b30 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
31b40 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
31b50 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
31b60 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
31b70 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
31b80 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
31b90 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
31ba0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
31bb0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
31bc0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
31bd0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
31be0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
31bf0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
31c00 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
31c10 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
31c20 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
31c30 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
31c40 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
31c50 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
31c60 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
31c70 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
31c80 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
31c90 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
31ca0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
31cb0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
31cc0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
31cd0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
31ce0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
31cf0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
31d00 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
31d10 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
31d20 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
31d30 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
31d40 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
31d50 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
31d60 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
31d70 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
31d80 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
31d90 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
31da0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
31db0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
31dc0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
31dd0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
31de0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
31df0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
31e00 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
31e10 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
31e20 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
31e30 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
31e40 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
31e50 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
31e60 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
31e70 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
31e80 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
31e90 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
31ea0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
31eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
31ec0 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
31ed0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
31ee0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
31ef0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
31f00 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
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 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
31f30 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
31f40 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
31f50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31f60 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
31f70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
31f80 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
31f90 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
31fa0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
31fb0 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
31fc0 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
31fd0 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
31fe0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
31ff0 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
32000 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
32010 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
32020 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
32030 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
32040 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32050 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
32060 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
32070 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
32080 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
32090 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
320a0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
320b0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
320c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
320d0 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
320e0 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
320f0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
32100 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
32110 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
32120 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
32130 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
32140 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
32150 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
32160 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
32170 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
32180 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
32190 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
321a0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
321b0 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
321c0 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
321d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
321e0 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
321f0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
32200 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
32210 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
32220 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
32230 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
32240 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
32250 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
32260 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
32270 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
32280 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
32290 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
322a0 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
322b0 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
322c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
322d0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
322e0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
322f0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
32300 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32310 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
32320 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
32330 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
32340 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
32350 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
32360 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
32370 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
32380 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
32390 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
323a0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
323b0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
323c0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
323d0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
323e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
323f0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
32400 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
32410 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
32420 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
32430 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
32440 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
32450 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
32460 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
32470 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
32480 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
32490 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
324a0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
324b0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
324c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
324d0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
324e0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
324f0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
32500 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
32510 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
32520 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
32530 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
32540 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
32550 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
32560 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
32570 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
32580 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
32590 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
325a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
325b0 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
325c0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
325d0 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
325e0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
325f0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
32600 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
32610 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
32620 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
32630 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
32640 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
32650 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
32660 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
32670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
32680 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
32690 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
326a0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
326b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
326c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
326d0 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
326e0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
326f0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
32700 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
32710 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
32720 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
32730 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
32740 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
32750 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
32760 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
32770 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
32780 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
32790 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
327a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
327b0 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
327c0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
327d0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
327e0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
327f0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32800 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
32810 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
32820 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
32830 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
32840 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
32850 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
32860 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
32870 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
32880 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
32890 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
328a0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
328b0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
328c0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
328d0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
328e0 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
328f0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32900 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
32910 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
32920 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
32930 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
32940 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
32950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
32960 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
32970 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
32980 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
32990 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
329a0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
329b0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
329c0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
329d0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
329e0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
329f0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
32a00 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
32a10 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
32a20 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
32a30 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
32a40 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
32a50 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
32a60 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
32a70 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
32a80 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
32a90 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
32aa0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
32ab0 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
32ac0 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
32ad0 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
32ae0 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
32af0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32b00 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
32b10 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
32b20 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32b30 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
32b40 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
32b50 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
32b60 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
32b70 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
32b80 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
32b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32ba0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
32bb0 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
32bc0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
32bd0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
32be0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32bf0 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
32c00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32c10 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
32c20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
32c30 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
32c40 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
32c50 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
32c60 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
32c70 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
32c80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
32c90 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
32ca0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
32cb0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
32cc0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32cd0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32ce0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
32cf0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
32d00 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32d10 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
32d20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
32d30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
32d40 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
32d50 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
32d60 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
32d70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
32d80 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
32d90 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
32da0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
32db0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
32dc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
32dd0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
32de0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
32df0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
32e00 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
32e10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32e20 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
32e30 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
32e40 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
32e50 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
32e60 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32e70 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
32e80 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
32e90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32ea0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32eb0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32ec0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
32ed0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32ee0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32ef0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
32f00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
32f10 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
32f20 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
32f30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
32f40 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
32f50 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
32f60 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
32f70 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
32f80 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
32f90 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
32fa0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
32fb0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
32fc0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
32fd0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f            1    /
32fe0 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33  * IMP: R-37514-3
32ff0 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20  5566 */.#define 
33000 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
33010 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d        2    /* IM
33020 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37  P: R-03371-37637
33030 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
33040 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
33050 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    3    /* IMP: R
33060 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a  -51971-34154 */.
33070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
33080 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
33090 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
330a0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
330b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
330c0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
330d0 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
330e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
330f0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
33100 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
33110 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33120 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
33130 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
33140 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
33150 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
33160 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
33170 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
33180 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
33190 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
331a0 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
331b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
331c0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
331d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
331e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
331f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
33200 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
33210 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33220 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
33230 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
33240 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
33250 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
33260 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
33270 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
33280 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
33290 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
332a0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
332b0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
332c0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
332d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
332e0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
332f0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
33300 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
33310 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
33320 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
33330 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
33340 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
33350 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
33360 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61  ons.  To encoura
33370 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74  ge programmers t
33380 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65  o avoid.** these
33390 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77   functions, we w
333a0 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20  ill not explain 
333b0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
333c0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
333d0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
333e0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
333f0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
33400 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
33410 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
33420 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
33430 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
33440 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
33450 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
33460 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
33470 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
33480 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
33490 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
334a0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
334b0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
334c0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
334d0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
334e0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
334f0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
33500 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
33510 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
33520 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
33530 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
33540 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
33550 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
33560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33570 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
33580 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
33590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
335a0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61  Obtaining SQL Va
335b0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
335c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
335d0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
335e0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
335f0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
33600 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
33610 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
33620 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
33630 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
33640 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
33650 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
33660 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
33670 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a  gregate.  .**.**
33680 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
33690 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
336a0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
336b0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
336c0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
336d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
336e0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
336f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33700 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
33710 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
33720 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
33730 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
33740 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
33750 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
33760 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
33770 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
33780 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
33790 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
337a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
337b0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
337c0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
337d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
337e0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
337f0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
33800 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
33810 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
33820 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
33830 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
33840 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33850 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
33860 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
33870 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
33880 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33890 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
338a0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
338b0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
338c0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
338d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
338e0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
338f0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
33900 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
33910 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
33920 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
33930 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
33940 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
33950 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
33960 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
33970 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
33980 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
33990 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
339a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
339b0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
339c0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
339d0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
339e0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
339f0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
33a00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
33a10 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
33a20 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
33a30 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
33a40 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
33a50 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
33a60 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
33a70 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
33a80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
33a90 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
33aa0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
33ab0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
33ac0 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
33ad0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
33ae0 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
33af0 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
33b00 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
33b10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
33b20 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
33b30 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
33b40 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
33b50 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
33b60 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
33b70 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
33b80 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
33b90 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
33ba0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
33bb0 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
33bc0 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
33bd0 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
33be0 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
33bf0 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
33c00 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
33c10 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
33c20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
33c30 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
33c40 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
33c50 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
33c60 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
33c70 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
33c80 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
33c90 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
33ca0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
33cb0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
33cc0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
33cd0 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
33ce0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
33cf0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
33d00 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
33d10 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
33d20 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
33d30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
33d40 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
33d50 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
33d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
33d70 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
33d80 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
33d90 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
33da0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
33db0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
33dc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
33dd0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
33de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33df0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
33e00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33e10 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
33e20 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
33e30 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
33e40 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
33e50 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
33e60 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
33e70 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
33e80 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
33e90 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
33ea0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
33eb0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
33ec0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
33ed0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
33ee0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33ef0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33f00 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
33f10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
33f20 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
33f30 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
33f40 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33f50 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
33f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33f70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
33f80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
33f90 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
33fa0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
33fb0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
33fc0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
33fd0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
33fe0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33ff0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
34000 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
34010 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34020 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
34030 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34040 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
34050 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34060 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
34070 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
34080 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
34090 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
340a0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
340b0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
340c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
340d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
340e0 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79  inding The Subty
340f0 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73  pe Of SQL Values
34100 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34110 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20  te3_value.**.** 
34120 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
34130 65 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e  e_subtype(V) fun
34140 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
34150 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a  e subtype for.**
34160 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   an [application
34170 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
34180 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20  ction] argument 
34190 56 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a  V.  The subtype.
341a0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63  ** information c
341b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61  an be used to pa
341c0 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f  ss a limited amo
341d0 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66  unt of context f
341e0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66  rom.** one SQL f
341f0 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68  unction to anoth
34200 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  er.  Use the [sq
34210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
34220 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  type()].** routi
34230 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75  ne to set the su
34240 62 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65  btype for the re
34250 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
34260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
34270 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  *.** SQLite make
34280 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74  s no use of subt
34290 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20  ype itself.  It 
342a0 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68  merely passes th
342b0 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f  e subtype.** fro
342c0 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  m the result of 
342d0 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  one [application
342e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
342f0 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a  ction] into the.
34300 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74  ** input of anot
34310 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64  her..*/.unsigned
34320 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
34330 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74  ue_subtype(sqlit
34340 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
34350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70  ** CAPI3REF: Cop
34360 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56  y And Free SQL V
34370 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
34380 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
34390 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
343a0 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
343b0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
343c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
343d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
343e0 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74  object D and ret
343f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
34400 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54  o that copy.  ^T
34410 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
34420 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  e] returned.** i
34430 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  s a [protected s
34440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34450 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65  ject even if the
34460 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a   input is not..*
34470 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
34480 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65  alue_dup(V) inte
34490 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
344a0 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20  LL if V is NULL 
344b0 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72  or if a.** memor
344c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
344d0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ls..**.** ^The s
344e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
344f0 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66  e(V) interface f
34500 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  rees an [sqlite3
34510 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
34520 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
34530 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
34540 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
34550 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55  .  ^If V is a NU
34560 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  LL pointer.** th
34570 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  en sqlite3_value
34580 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61  _free(V) is a ha
34590 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
345a0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
345b0 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  NTAL sqlite3_val
345c0 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ue *sqlite3_valu
345d0 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
345e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
345f0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
34600 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61   void sqlite3_va
34610 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
34620 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
34630 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
34640 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
34650 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
34660 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
34670 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
34680 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
34690 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
346a0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
346b0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
346c0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
346d0 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
346e0 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
346f0 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
34700 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
34710 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
34720 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
34730 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
34740 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
34750 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
34760 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
34770 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
34780 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
34790 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
347a0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
347b0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
347c0 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
347d0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
347e0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
347f0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34800 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
34810 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
34820 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
34830 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
34840 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
34850 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34860 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
34870 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
34880 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
34890 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
348a0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
348b0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
348c0 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
348d0 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
348e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
348f0 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
34900 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
34910 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
34920 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
34930 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
34940 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
34950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
34960 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
34970 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
34980 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
34990 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
349a0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
349b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
349c0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
349d0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
349e0 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
349f0 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
34a00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34a10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
34a20 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
34a30 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
34a40 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
34a50 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
34a60 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
34a70 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
34a80 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
34a90 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
34aa0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
34ab0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
34ac0 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
34ad0 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
34ae0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
34af0 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
34b00 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
34b10 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
34b20 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
34b30 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
34b40 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
34b50 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
34b60 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
34b70 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
34b80 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
34b90 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
34ba0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
34bb0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
34bc0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
34bd0 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
34be0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
34bf0 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
34c00 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
34c10 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
34c20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34c30 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
34c40 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
34c50 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
34c60 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
34c70 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
34c80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
34c90 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
34ca0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
34cb0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34cc0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
34cd0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
34ce0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
34cf0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
34d00 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
34d10 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
34d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
34d30 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
34d40 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
34d50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
34d60 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
34d70 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
34d80 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
34d90 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
34da0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
34db0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
34dc0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34dd0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
34de0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
34df0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
34e00 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
34e10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
34e20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
34e30 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
34e40 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
34e50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
34e60 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
34e70 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
34e80 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
34e90 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
34ea0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
34eb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34ec0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
34ed0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34ee0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
34ef0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
34f00 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
34f10 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
34f20 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
34f30 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34f40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34f50 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
34f60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34f70 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
34f80 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
34f90 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
34fa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
34fb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
34fc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34fd0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
34fe0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34ff0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
35000 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
35010 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35020 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
35030 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
35040 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
35050 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
35060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35070 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
35080 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
35090 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
350a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
350b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
350c0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
350d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
350e0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
350f0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
35100 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
35110 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
35120 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
35130 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
35140 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35150 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
35160 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35170 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
35180 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
35190 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
351a0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
351b0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
351c0 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
351d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
351e0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
351f0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
35200 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
35210 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
35220 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Data.** METHOD:
35230 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
35240 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
35250 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
35260 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
35270 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
35280 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
35290 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
352a0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
352b0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
352c0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
352d0 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
352e0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
352f0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
35300 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
35310 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
35320 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
35330 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
35340 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
35350 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
35360 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
35370 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
35380 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
35390 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
353a0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
353b0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
353c0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
353d0 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
353e0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
353f0 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
35400 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
35410 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
35420 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
35430 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
35440 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
35450 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
35460 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
35470 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
35480 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
35490 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
354a0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
354b0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
354c0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
354d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
354e0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
354f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35500 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
35510 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
35520 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
35530 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35540 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
35550 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
35560 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
35570 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35580 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
35590 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
355a0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
355b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
355c0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
355d0 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
355e0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
355f0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
35600 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
35610 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
35620 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35630 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
35640 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
35650 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
35660 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
35670 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
35680 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35690 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
356a0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
356b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
356c0 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
356d0 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
356e0 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
356f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
35700 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
35710 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
35720 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
35730 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
35740 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
35750 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
35760 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
35770 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35780 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
35790 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
357a0 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
357b0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
357c0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
357d0 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
357e0 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
357f0 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
35800 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
35810 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
35820 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
35830 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
35840 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
35850 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
35860 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
35870 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
35880 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
35890 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
358a0 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
358b0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
358c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
358d0 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
358e0 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
358f0 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
35900 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
35910 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
35920 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
35930 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
35940 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
35950 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
35960 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
35970 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
35980 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
35990 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
359a0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
359b0 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
359c0 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
359d0 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
359e0 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
359f0 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
35a00 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35a10 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
35a20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
35a30 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
35a40 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
35a50 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
35a60 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
35a70 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
35a80 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
35a90 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
35aa0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
35ab0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35ac0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35ad0 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
35ae0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35af0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
35b00 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
35b10 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
35b20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
35b30 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
35b40 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
35b50 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
35b60 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
35b70 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
35b80 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
35b90 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
35ba0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
35bb0 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
35bc0 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
35bd0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
35be0 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
35bf0 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
35c00 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
35c10 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
35c20 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
35c30 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
35c40 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
35c50 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
35c60 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
35c70 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
35c80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
35c90 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
35ca0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
35cb0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
35cc0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
35cd0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
35ce0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
35cf0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
35d00 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
35d10 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
35d20 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
35d30 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
35d40 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
35d50 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
35d60 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
35d70 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
35d80 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
35d90 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
35da0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
35db0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
35dc0 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
35dd0 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
35de0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
35df0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
35e00 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
35e10 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
35e20 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
35e30 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
35e40 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
35e50 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
35e60 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
35e70 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
35e80 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
35e90 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
35ea0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
35eb0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
35ec0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
35ed0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
35ee0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
35ef0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
35f00 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
35f10 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
35f20 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
35f30 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
35f40 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
35f50 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
35f60 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
35f70 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
35f80 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
35f90 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
35fa0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
35fb0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
35fc0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
35fd0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
35fe0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
35ff0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
36000 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
36010 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
36020 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
36030 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
36040 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  n.** METHOD: sql
36050 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
36060 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
36070 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
36080 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
36090 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
360a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
360b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
360c0 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
360d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
360e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
360f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
36100 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
36110 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
36120 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
36130 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
36140 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
36150 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
36160 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
36170 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
36180 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
36190 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
361a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
361b0 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
361c0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
361d0 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
361e0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
361f0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
36200 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
36210 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
36220 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
36230 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
36240 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
36250 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
36260 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36270 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
36280 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
36290 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
362a0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
362b0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
362c0 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
362d0 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
362e0 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
362f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
36300 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36310 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
36320 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
36330 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43  ult_zeroblob64(C
36340 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ,N).** interface
36350 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
36360 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
36370 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36380 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
36390 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
363a0 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61  all zero bytes a
363b0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
363c0 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ze..**.** ^The s
363d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
363e0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
363f0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
36400 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
36410 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36420 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
36430 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
36440 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
36450 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
36460 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
36470 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36480 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
36490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
364a0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
364b0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
364c0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
364d0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
364e0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
364f0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
36500 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
36510 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
36520 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
36530 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36540 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
36550 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
36560 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
36570 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
36580 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
36590 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
365a0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
365b0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
365c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
365d0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
365e0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
365f0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
36600 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
36610 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
36620 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
36630 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
36640 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
36650 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
36660 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
36670 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
36680 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
36690 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
366a0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
366b0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
366c0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
366d0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
366e0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
366f0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
36700 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
36710 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
36720 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
36730 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36740 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
36750 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
36760 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
36770 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
36780 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
36790 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
367a0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
367b0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
367c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
367d0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
367e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
367f0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
36800 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
36810 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
36820 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
36830 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
36840 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
36850 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
36860 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
36870 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
36880 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
36890 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
368a0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
368b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
368c0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
368d0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
368e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
368f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
36900 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
36910 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
36920 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
36930 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
36940 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
36950 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
36960 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
36970 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
36980 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
36990 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
369a0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
369b0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
369c0 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
369d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
369e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
369f0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
36a00 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
36a10 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
36a20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
36a30 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
36a40 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
36a50 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
36a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36a70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36a80 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
36a90 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
36aa0 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
36ab0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
36ac0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
36ad0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
36ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36af0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
36b00 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
36b10 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
36b20 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
36b30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36b40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
36b50 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
36b60 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
36b70 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
36b80 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
36b90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36ba0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
36bb0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
36bc0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
36bd0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
36be0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36bf0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
36c00 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
36c10 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
36c20 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
36c30 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
36c40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36c50 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
36c60 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
36c70 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
36c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36c90 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36ca0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
36cb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36cc0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
36cd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36ce0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
36cf0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
36d00 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
36d10 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
36d20 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
36d30 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
36d40 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
36d50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36d60 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
36d70 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
36d80 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
36d90 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
36da0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
36db0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
36dc0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
36dd0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
36de0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
36df0 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  vely..** ^The sq
36e00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36e10 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
36e20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
36e30 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61  value of an.** a
36e40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36e50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36e60 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  e a text string 
36e70 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a  in an encoding.*
36e80 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  * specified by t
36e90 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61  he fifth (and la
36ea0 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77  st) parameter, w
36eb0 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65  hich must be one
36ec0 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  .** of [SQLITE_U
36ed0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
36ee0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
36ef0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
36f00 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20  TE_UTF16LE]..** 
36f10 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
36f20 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
36f30 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
36f40 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
36f50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
36f60 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
36f70 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
36f80 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
36f90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
36fa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
36fb0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
36fc0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
36fd0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
36fe0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
36ff0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
37000 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
37010 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
37020 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
37030 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
37040 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
37050 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37060 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
37070 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
37080 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
37090 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
370a0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
370b0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
370c0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
370d0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
370e0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
370f0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
37100 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
37110 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
37120 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
37130 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
37140 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
37150 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
37160 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
37170 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
37180 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
37190 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
371a0 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
371b0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
371c0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
371d0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
371e0 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
371f0 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
37200 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
37210 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
37220 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
37230 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
37240 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
37250 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
37260 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
37270 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
37280 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
37290 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
372a0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
372b0 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
372c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
372d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
372e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
372f0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
37300 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
37310 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
37320 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
37330 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
37340 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
37350 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
37360 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
37370 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
37380 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
37390 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
373a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
373b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
373c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
373d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
373e0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
373f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
37400 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
37410 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
37420 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
37430 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
37440 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
37450 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
37460 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
37470 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
37480 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
37490 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
374a0 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
374b0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
374c0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
374d0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
374e0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
374f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
37500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
37510 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37520 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37530 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
37540 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
37550 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
37560 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
37570 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
37580 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
37590 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
375a0 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
375b0 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
375c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
375d0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
375e0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
375f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
37600 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
37610 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
37620 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
37630 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37640 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
37650 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
37660 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
37670 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37680 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
37690 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
376a0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
376b0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
376c0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
376d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
376e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
376f0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
37700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
37710 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
37720 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
37730 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
37740 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
37750 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
37760 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
37770 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
37780 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
37790 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
377a0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
377b0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
377c0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
377d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
377e0 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
377f0 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
37800 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
37810 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
37820 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
37830 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
37840 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
37850 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
37860 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
37870 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
37880 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
37890 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
378a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
378b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
378c0 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
378d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
378e0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
378f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
37900 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
37910 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37920 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
37930 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37940 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
37950 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37960 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37970 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63  blob64(sqlite3_c
37980 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f  ontext*,const vo
37990 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  id*,.           
379a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
379b0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76  sqlite3_uint64,v
379c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
379d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
379e0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
379f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
37a00 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
37a10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
37a20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37a30 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
37a40 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
37a50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
37a60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37a70 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
37a80 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
37a90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
37aa0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
37ab0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
37ac0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37ad0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
37ae0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
37af0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37b00 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
37b10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37b20 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
37b30 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
37b40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37b50 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
37b60 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
37b70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37b80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
37b90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37ba0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
37bb0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
37bc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37bd0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
37be0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
37bf0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
37c00 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
37c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37c20 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt64(sqlite3_con
37c30 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
37c40 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
37c50 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
37c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
37c70 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
37c80 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
37c90 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ding);.void sqli
37ca0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37cb0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
37cc0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37cd0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
37ce0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
37cf0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37d00 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
37d10 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37d20 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
37d30 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
37d40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37d50 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
37d60 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
37d70 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
37d80 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
37d90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37da0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
37db0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
37dc0 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
37dd0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
37de0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
37df0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74  xt*, int n);.int
37e00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37e10 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
37e20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
37e30 69 74 65 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a  ite3_uint64 n);.
37e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37e50 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 53 75  : Setting The Su
37e60 62 74 79 70 65 20 4f 66 20 41 6e 20 53 51 4c 20  btype Of An SQL 
37e70 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48  Function.** METH
37e80 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
37e90 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ext.**.** The sq
37ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
37eb0 74 79 70 65 28 43 2c 54 29 20 66 75 6e 63 74 69  type(C,T) functi
37ec0 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 73 75  on causes the su
37ed0 62 74 79 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20  btype of.** the 
37ee0 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
37ef0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
37f00 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
37f10 6e 5d 20 77 69 74 68 20 0a 2a 2a 20 5b 73 71 6c  n] with .** [sql
37f20 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 20  ite3_context] C 
37f30 74 6f 20 62 65 20 74 68 65 20 76 61 6c 75 65 20  to be the value 
37f40 54 2e 20 20 4f 6e 6c 79 20 74 68 65 20 6c 6f 77  T.  Only the low
37f50 65 72 20 38 20 62 69 74 73 20 0a 2a 2a 20 6f 66  er 8 bits .** of
37f60 20 74 68 65 20 73 75 62 74 79 70 65 20 54 20 61   the subtype T a
37f70 72 65 20 70 72 65 73 65 72 76 65 64 20 69 6e 20  re preserved in 
37f80 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 73  current versions
37f90 20 6f 66 20 53 51 4c 69 74 65 3b 0a 2a 2a 20 68   of SQLite;.** h
37fa0 69 67 68 65 72 20 6f 72 64 65 72 20 62 69 74 73  igher order bits
37fb0 20 61 72 65 20 64 69 73 63 61 72 64 65 64 2e 0a   are discarded..
37fc0 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** The number of
37fd0 20 73 75 62 74 79 70 65 20 62 79 74 65 73 20 70   subtype bytes p
37fe0 72 65 73 65 72 76 65 64 20 62 79 20 53 51 4c 69  reserved by SQLi
37ff0 74 65 20 6d 69 67 68 74 20 69 6e 63 72 65 61 73  te might increas
38000 65 0a 2a 2a 20 69 6e 20 66 75 74 75 72 65 20 72  e.** in future r
38010 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
38020 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
38030 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70  e3_result_subtyp
38040 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
38050 74 2a 2c 75 6e 73 69 67 6e 65 64 20 69 6e 74 29  t*,unsigned int)
38060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38070 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
38080 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
38090 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
380a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
380b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
380c0 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
380d0 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
380e0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
380f0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
38100 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
38110 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
38120 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
38130 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
38140 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
38150 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
38160 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
38170 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38180 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
38190 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
381a0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
381b0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
381c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
381d0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
381e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
381f0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
38200 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
38210 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
38220 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
38230 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
38240 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
38250 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
38260 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
38270 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
38280 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
38290 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
382a0 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
382b0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
382c0 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
382d0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
382e0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
382f0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
38300 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
38310 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
38320 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
38330 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
38340 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
38350 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
38360 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
38370 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
38380 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
38390 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
383a0 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
383b0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
383c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
383d0 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
383e0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
383f0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
38400 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
38410 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
38420 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
38430 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
38440 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
38450 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
38460 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
38470 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
38480 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
38490 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
384a0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
384b0 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
384c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
384d0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
384e0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
384f0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
38500 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
38510 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
38520 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
38530 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
38540 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
38550 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
38560 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
38570 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
38580 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
38590 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
385a0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
385b0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
385c0 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
385d0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
385e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
385f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
38600 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
38610 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
38620 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
38630 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
38640 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
38650 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
38660 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
38670 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
38680 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
38690 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
386a0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
386b0 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
386c0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
386d0 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
386e0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
386f0 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
38700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
38710 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
38720 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
38730 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
38740 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
38750 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
38760 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
38770 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
38780 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
38790 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
387a0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
387b0 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
387c0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
387d0 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
387e0 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
387f0 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
38800 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
38810 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
38820 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
38830 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
38840 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
38850 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
38860 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
38870 6e 67 20 66 75 6e 63 74 69 6f 6