/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 86884a006a451c22d342da18d8e373aa70e65ec0:


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 73 71 6c 69 74  eter of.** sqlit
39c0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
39d0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
39e0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
39f0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3a00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3a30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3a40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3a50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3a60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3a70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3a80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3a90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3aa0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3ab0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ac0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3ad0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3af0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3b00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3b10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3b20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3b30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3b40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3b50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3b60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3b70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3b80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3b90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ba0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3bb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3bc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3bd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3be0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3bf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3c10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3c20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3c30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3c40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3c50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3c60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3c70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3c80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3c90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3ca0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3cb0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3cc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3cd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ce0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3cf0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3d20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3d50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3d60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3d70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3d80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3d90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3da0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3db0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3dc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3dd0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3de0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3df0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3e00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3e10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3e20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3e30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3e40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3e50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3e60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3e70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3e80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3e90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3ea0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3eb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3ec0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ed0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3ee0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
3ef0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
3f00: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3f10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3f20: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
3f30: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
3f40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3f50: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3f60: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
3f70: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
3f80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3f90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3fa0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3fd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fe0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ff0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4000: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4010: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4020: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4030: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4040: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4050: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4060: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4070: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4080: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4090: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
40a0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  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 2f                 /
40d0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
40e0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
40f0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4120: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4130: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4140: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4150: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4160: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4170: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  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 2f                 /
41a0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
41b0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
41c0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  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 2f 2a 20 45 72             /* Er
41f0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4200: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4210: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4220: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4230: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4240: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4250: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4260: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4270: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
4280: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
4290: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
42a0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
42b0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
42c0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
42d0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
42e0: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
42f0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4300: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4310: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4320: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4330: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4340: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4350: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4360: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4370: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4380: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4390: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43a0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
43b0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
43c0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
43d0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
43e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
43f0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4400: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4410: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4420: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4430: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4440: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4450: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4470: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4480: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4490: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44a0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
44b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
44c0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
44d0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
44e0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
44f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4500: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4510: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4520: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4530: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4540: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4550: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4560: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4580: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4590: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45a0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
45b0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
45c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
45d0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
45e0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
45f0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4600: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4620: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4630: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4640: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4650: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4660: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4670: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4680: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4690: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46b0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
46c0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
46d0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
46e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
46f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4700: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4710: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4720: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4730: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4760: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4770: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4780: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4790: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47a0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
47b0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
47c0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
47d0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
47e0: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
47f0: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4810: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4820: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4830: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4840: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4850: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4860: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4870: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4880: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48a0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
48b0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
48c0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
48d0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
48e0: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
48f0: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4900: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4920: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4930: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4940: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4960: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4970: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4980: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4990: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
49b0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
49c0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
49d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
49e0: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
49f0: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a00: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a10: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a20: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a30: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a40: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4a50: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4a60: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a70: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a80: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a90: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4aa0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4ab0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4ad0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4ae0: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4af0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b10: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4b20: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4b30: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b50: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4b60: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4b70: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4b80: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4ba0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4bb0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4bc0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4bd0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4be0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4bf0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4c00: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4c10: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4c20: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4c30: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4c40: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4c50: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4c60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4c70: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4c80: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4c90: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4ca0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4cb0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4cc0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4cd0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4ce0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4cf0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4d00: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4d10: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4d20: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4d30: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4d40: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4d50: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4d60: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4d70: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4d80: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4d90: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4da0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
4db0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
4dc0: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
4dd0: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
4de0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
4df0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
4e00: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
4e10: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
4e20: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
4e30: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
4e40: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4e50: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4e60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4e70: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4e80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4e90: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4ea0: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
4eb0: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
4ec0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
4ed0: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
4ee0: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
4ef0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
4f00: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
4f10: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
4f20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f30: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f50: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4f60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4f70: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4f90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fa0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4fe0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4ff0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5000: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5010: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5020: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5030: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5040: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5050: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5060: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
5070: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5080: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
5090: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50a0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
50b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50c0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
50d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50e0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
50f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5100: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5120: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5130: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5140: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
5170: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5180: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
5190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51a0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
51b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51c0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5240: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5260: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
5270: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
5280: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
5290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52a0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
52b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52c0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52e0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
52f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5300: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5320: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5340: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
5350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5360: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
5370: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5380: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
5390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53a0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
53b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53c0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
53d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53e0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
53f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5400: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5420: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5430: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5440: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
5450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5460: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
5470: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5480: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
5490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54a0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
54b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54c0: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
54d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54e0: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
54f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5500: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5510: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5520: 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20  ERR_GETTEMPPATH 
5530: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5540: 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23  ERR | (25<<8)).#
5550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5560: 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  ERR_CONVPATH    
5570: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5580: 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23  ERR | (26<<8)).#
5590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55a0: 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20  ERR_VNODE       
55b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
55c0: 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23  ERR | (27<<8)).#
55d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55e0: 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20  ERR_AUTH        
55f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5600: 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23  ERR | (28<<8)).#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5620: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5630: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5640: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5660: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5670: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5680: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56a0: 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20  BUSY_SNAPSHOT   
56b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56c0: 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29  BUSY   |  (2<<8)
56d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56e0: 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50  _CANTOPEN_NOTEMP
56f0: 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  DIR      (SQLITE
5700: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c  _CANTOPEN | (1<<
5710: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5720: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49  TE_CANTOPEN_ISDI
5730: 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  R          (SQLI
5740: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32  TE_CANTOPEN | (2
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55  LITE_CANTOPEN_FU
5770: 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51  LLPATH       (SQ
5780: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5790: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
57a0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57b0: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28  CONVPATH       (
57c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
57d0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
57e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
57f0: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20  _VTAB           
5800: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5810: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5830: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5840: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5850: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5870: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5880: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5890: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
58a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
58b0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
58c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
58d0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
58e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58f0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5900: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5910: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5920: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5930: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
5940: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5950: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
5960: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43  _CONSTRAINT_CHEC
5980: 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  K        (SQLITE
5990: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31  _CONSTRAINT | (1
59a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59c0: 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51  COMMITHOOK   (SQ
59d0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59e0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
59f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a00: 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20  INT_FOREIGNKEY  
5a10: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a20: 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  INT | (3<<8)).#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a40: 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e  STRAINT_FUNCTION
5a50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a60: 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29  STRAINT | (4<<8)
5a70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e  _CONSTRAINT_NOTN
5a90: 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  ULL      (SQLITE
5aa0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35  _CONSTRAINT | (5
5ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ad0: 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51  PRIMARYKEY   (SQ
5ae0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5af0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5b00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b10: 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20  INT_TRIGGER     
5b20: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b30: 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  INT | (7<<8)).#d
5b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b50: 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20  STRAINT_UNIQUE  
5b60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b70: 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29  STRAINT | (8<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42  _CONSTRAINT_VTAB
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39  _CONSTRAINT | (9
5bc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bd0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5be0: 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51  ROWID        (SQ
5bf0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c00: 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e  |(10<<8)).#defin
5c10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c20: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5c30: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c40: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c50: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c60: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5c70: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c80: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5c90: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
5ca0: 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20  _AUTOINDEX      
5cb0: 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47   (SQLITE_WARNING
5cc0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5cd0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55  ne SQLITE_AUTH_U
5ce0: 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20  SER             
5cf0: 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c    (SQLITE_AUTH |
5d00: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
5d10: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
5d20: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
5d30: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
5d40: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5d50: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5d60: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5d70: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5d80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5d90: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5da0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5db0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5dc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
5dd0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
5de0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5df0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5e00: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5e10: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
5e20: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5e40: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
5e50: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5e60: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5e70: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5e90: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5ea0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5eb0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5ec0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5ed0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ee0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5ef0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5f00: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
5f10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5f20: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
5f30: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5f40: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
5f50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5f60: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5f70: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5f80: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5f90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5fa0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
5fb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5fc0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
5fd0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5fe0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5ff0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6000: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6010: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6020: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6030: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6040: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6050: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6060: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6070: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6080: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6090: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
60a0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
60b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
60c0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
60d0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
60e0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
60f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6100: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6110: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6120: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6130: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6140: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6150: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6160: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6170: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6180: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6190: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
61a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
61b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61c0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
61d0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
61e0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
61f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6200: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6210: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6220: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6230: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6240: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6250: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6260: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6270: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6280: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6290: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62a0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
62b0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
62c0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
62d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
62e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62f0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6300: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6310: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6320: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6330: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6340: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6350: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6360: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6370: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6380: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6390: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
63a0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
63b0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
63c0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
63d0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
63e0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
63f0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
6400: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6410: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6420: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6430: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6440: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6450: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6460: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6470: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6480: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6490: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
64a0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
64b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
64c0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
64d0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
64e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
64f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6500: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6510: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6520: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6530: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6540: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6550: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6560: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6570: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6580: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6590: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
65a0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
65b0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
65c0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
65d0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
65e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
65f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6600: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6610: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6620: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6630: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6640: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6650: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6660: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6670: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6680: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6690: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
66a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
66b0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
66c0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
66d0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
66e0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
66f0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6700: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6710: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6720: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6730: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6740: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6750: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6760: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6770: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6780: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6790: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
67a0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
67b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
67c0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
67d0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
67e0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
67f0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6800: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6810: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6820: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6830: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6840: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6850: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6860: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6870: 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  te that a file c
6880: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6890: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
68a0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
68b0: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
68c0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
68d0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
68e0: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
68f0: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6900: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6910: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6920: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6930: 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  eges..*/.#define
6940: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6950: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6960: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6980: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6990: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
69a0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
69b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
69c0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
69d0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
69e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69f0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
6a00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a10: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6a20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a30: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6a40: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6a50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a60: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a80: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6a90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6aa0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6ab0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
6ac0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ad0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
6ae0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6af0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
6b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b20: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6b40: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6b50: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6b60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b70: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6b80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b90: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6ba0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6bb0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6bc0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6be0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6bf0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6c00: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
6c10: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6c20: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  LE              
6c30: 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a  0x00002000../*.*
6c40: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
6c50: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6c60: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6c70: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6c80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6c90: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6ca0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6cb0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6cc0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6cd0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6ce0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6cf0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6d00: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6d10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6d20: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6d30: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6d40: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
6d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6d60: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6d70: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6d80: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6d90: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6da0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6db0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6dc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6dd0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6de0: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6df0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
6e00: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
6e10: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
6e20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6e30: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
6e40: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
6e50: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
6e60: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6e70: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
6e80: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
6e90: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6ea0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
6eb0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
6ec0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
6ed0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
6ee0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
6ef0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
6f00: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
6f10: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
6f20: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
6f30: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6f40: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
6f50: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
6f60: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
6f70: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
6f80: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
6f90: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
6fa0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6fb0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
6fc0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6fd0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6fe0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6ff0: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
7000: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
7010: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
7020: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
7030: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7040: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7050: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
7060: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7070: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
7080: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7090: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
70a0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
70b0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
70c0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
70d0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
70e0: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
70f0: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
7100: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
7110: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
7120: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
7130: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7140: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7150: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
7160: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
7170: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
7180: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
7190: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
71a0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
71b0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
71c0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
71d0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
71e0: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
71f0: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
7200: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
7210: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7220: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7230: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7240: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7250: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7260: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7270: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
7280: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
7290: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
72a0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
72b0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
72c0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
72d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
72e0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
72f0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
7300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7310: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7320: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7330: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7340: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7350: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7360: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7370: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
7380: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
7390: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
73a0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
73b0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
73c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
73d0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
73e0: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
73f0: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
7400: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7410: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7420: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7430: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7440: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7450: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7460: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7470: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7480: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7490: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
74a0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
74b0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
74c0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
74d0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
74e0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
74f0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7500: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7510: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7520: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7530: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7540: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7550: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7560: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7570: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7580: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7590: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
75a0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
75b0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
75c0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
75d0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
75e0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
75f0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7600: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7610: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7620: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7630: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7640: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7650: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7660: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7670: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7680: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7690: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
76a0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
76b0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
76c0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
76d0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
76e0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
76f0: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7700: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7710: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7720: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7730: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7740: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7750: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7760: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7770: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7780: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7790: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
77a0: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
77b0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
77c0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
77d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
77e0: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
77f0: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7800: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7810: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7820: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7830: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7840: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7850: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7860: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7870: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7880: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7890: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
78a0: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
78b0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
78c0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
78d0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
78e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
78f0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7900: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
7910: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7920: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7930: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7940: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
7950: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7960: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7970: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7980: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7990: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
79a0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
79b0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
79c0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
79d0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
79e0: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
79f0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
7a00: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
7a10: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
7a20: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
7a30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7a40: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
7a50: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7a60: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7a70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7a80: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7a90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7aa0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7ab0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7ac0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7ad0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7ae0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7af0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
7b00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7b10: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
7b20: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
7b30: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
7b40: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
7b50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7b60: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7b70: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7b80: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7b90: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7ba0: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7bb0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7bc0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7bd0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7be0: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7bf0: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
7c00: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
7c10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
7c20: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
7c30: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
7c40: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
7c50: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7c60: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7c70: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7c80: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7c90: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7ca0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7cb0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7cc0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7cd0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7ce0: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7cf0: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7d00: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7d10: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7d20: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7d30: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7d40: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
7d50: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
7d60: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7d70: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7d80: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7d90: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7da0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7db0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7dc0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7dd0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7de0: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7df0: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
7e00: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
7e10: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
7e20: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
7e30: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
7e40: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
7e50: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
7e60: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
7e70: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
7e80: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
7e90: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
7ea0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
7eb0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
7ec0: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ** A [file contr
7ed0: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73  ol opcodes | lis
7ee0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7ef0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7f00: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7f10: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7f20: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7f30: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7f40: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7f50: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7f60: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7f70: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7f80: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7f90: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7fa0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7fb0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7fc0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7fd0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7fe0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7ff0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8000: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8010: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8020: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8030: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8040: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8050: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8060: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8070: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
8080: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
8090: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
80a0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
80b0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
80c0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
80d0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
80e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
80f0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8100: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8110: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8120: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8130: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8140: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8150: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8160: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8170: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
8180: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8190: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
81a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81b0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
81c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81d0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
81e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81f0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8200: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8210: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8220: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8230: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8240: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8250: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8260: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8270: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
8280: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8290: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
82a0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
82b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
82c0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
82d0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
82e0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
82f0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8300: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8310: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8320: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8330: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8340: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8350: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8360: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8370: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
8380: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
8390: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
83a0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
83b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
83c0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
83d0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
83e0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
83f0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8400: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8410: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8420: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8430: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8440: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8450: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8460: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8470: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8480: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
8490: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
84a0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
84b0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
84c0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
84d0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
84e0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
84f0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8500: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8510: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8520: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8530: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8540: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8550: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8560: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8570: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8580: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
8590: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
85a0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
85b0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
85c0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
85d0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
85e0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
85f0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8600: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8610: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8620: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8630: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8640: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8650: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8660: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8680: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8690: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
86a0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
86b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
86c0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
86d0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
86e0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
86f0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8700: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8710: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8720: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8730: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8740: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8750: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8760: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8770: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8780: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8790: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
87a0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
87b0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
87c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
87d0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
87e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
87f0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8800: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8810: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8820: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8830: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8840: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8850: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8860: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8870: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8880: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8890: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
88a0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
88b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
88c0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
88d0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
88e0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
88f0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8910: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8920: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8930: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8940: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8950: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8960: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8970: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
8980: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8990: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
89a0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
89b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
89c0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
89d0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
89e0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
89f0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8a00: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8a10: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8a20: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8a30: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8a40: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8a50: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8a60: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8a70: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8a80: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8a90: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8aa0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8ab0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
8ac0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
8ad0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8ae0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8af0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8b00: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8b10: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8b20: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
8b30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8b40: 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74  odes} {file cont
8b50: 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a  rol opcode}.**.*
8b60: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8b70: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
8b80: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
8b90: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8ba0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8bb0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8bc0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8bd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8be0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8bf0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
8c00: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53   <ul>.** <li>[[S
8c10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8c20: 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  STATE]].** The [
8c30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8c40: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
8c50: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
8c60: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8c70: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8c80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8c90: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8ca0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8cb0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8cc0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8cd0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8ce0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8cf0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8d00: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
8d10: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8d20: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
8d30: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
8d40: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
8d50: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
8d60: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
8d70: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
8d80: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
8d90: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
8da0: 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  d is only availa
8db0: 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c  ble when the SQL
8dc0: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70  ITE_TEST.** comp
8dd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
8de0: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
8df0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e00: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
8e10: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e20: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
8e30: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
8e40: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
8e50: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
8e60: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
8e70: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
8e80: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
8e90: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
8ea0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
8eb0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
8ec0: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
8ed0: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
8ee0: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
8ef0: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
8f00: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
8f10: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
8f20: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
8f30: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8f40: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
8f50: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
8f60: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
8f70: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
8f80: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
8f90: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
8fa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8fb0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
8fc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8fd0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
8fe0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
8ff0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
9000: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
9010: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
9020: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
9030: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
9040: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
9050: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
9060: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
9070: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
9080: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
9090: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
90a0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
90b0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
90c0: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
90d0: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
90e0: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
90f0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
9100: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
9110: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
9120: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
9130: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
9140: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
9150: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
9160: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
9170: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
9180: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
9190: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
91a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
91b0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
91c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
91d0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
91e0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
91f0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9200: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9210: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9220: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9230: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9240: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9250: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9260: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9270: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  RNAL_POINTER]..*
9280: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9290: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
92a0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
92b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
92c0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20  OURNAL_POINTER] 
92d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
92e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
92f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9300: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9310: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9320: 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66  th the journal f
9330: 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74  ile (either.** t
9340: 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  he [rollback jou
9350: 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72  rnal] or the [wr
9360: 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20  ite-ahead log]) 
9370: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
9380: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9390: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
93a0: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
93b0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a  _FILE_POINTER]..
93c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
93d0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
93e0: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
93f0: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9400: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9410: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9420: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9430: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9440: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9450: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9460: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
9470: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
9480: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
9490: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
94a0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
94b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
94c0: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
94d0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
94e0: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
94f0: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9500: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9510: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9520: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9530: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9540: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
9550: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
9560: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
9570: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9580: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
9590: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
95a0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
95b0: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
95c0: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
95d0: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
95e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
95f0: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9600: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9610: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9620: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9630: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9640: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
9650: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
9660: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
9670: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
9680: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
9690: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
96a0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
96b0: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
96c0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
96d0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
96e0: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
96f0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9700: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9710: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9720: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9730: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9740: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
9750: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9760: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9770: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9780: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9790: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
97a0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
97b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
97c0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
97d0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
97e0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
97f0: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9800: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9810: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9820: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9830: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9840: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
9850: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
9860: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
9870: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
9880: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
9890: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
98a0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
98b0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
98c0: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
98d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
98e0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
98f0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9900: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9910: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9920: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9930: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9940: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9950: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9970: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
9980: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9990: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
99a0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
99b0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
99c0: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
99d0: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
99e0: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
99f0: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9a00: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9a10: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9a20: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9a30: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9a40: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
9a50: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
9a60: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
9a70: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
9a80: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
9a90: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
9aa0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9ab0: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9ac0: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9ad0: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9ae0: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9af0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9b00: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9b10: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9b20: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9b30: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9b40: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
9b50: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
9b60: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
9b70: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9b80: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
9b90: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
9ba0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9bb0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9bc0: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9bd0: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9be0: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9bf0: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9c00: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9c10: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9c20: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9c30: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9c40: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
9c50: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
9c60: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
9c70: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
9c80: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9c90: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9ca0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9cb0: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9cc0: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9cd0: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9ce0: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9cf0: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9d00: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9d10: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9d20: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9d30: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9d40: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9d50: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9d60: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9d70: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9d80: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9d90: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9da0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9db0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9dc0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9dd0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9de0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9df0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9e00: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9e10: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9e20: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
9e30: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
9e40: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
9e50: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
9e60: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
9e70: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9e80: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9e90: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9ea0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9eb0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9ec0: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9ed0: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9ee0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9ef0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9f00: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9f10: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
9f20: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
9f30: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
9f40: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
9f50: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
9f60: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
9f70: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9f80: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9f90: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9fa0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9fb0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9fc0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9fd0: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9fe0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9ff0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a000: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a010: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a020: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a030: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a040: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
a050: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a060: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a070: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a080: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a090: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a0a0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a0b0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a0c0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a0d0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
a0e0: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
a0f0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
a100: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
a110: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a120: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a130: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a140: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a150: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
a160: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a170: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a180: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a190: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a1a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a1b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a1c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
a1d0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a1e0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a1f0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
a200: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
a210: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
a220: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
a230: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
a240: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
a250: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a260: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
a270: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
a280: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
a290: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
a2a0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a2b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a2c0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a2d0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a2e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a2f0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a300: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a310: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a320: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a330: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a340: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a350: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a360: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a370: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a380: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a390: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a3a0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a3b0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a3c0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a3d0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a3e0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a3f0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a400: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a410: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a420: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a430: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a440: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a450: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a460: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a470: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a480: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a490: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a4a0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a4b0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a4c0: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a4d0: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a4e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a4f0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a500: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a510: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a520: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a530: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a540: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a550: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a560: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a570: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a580: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a590: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a5a0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a5b0: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a5c0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a5d0: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a5e0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a5f0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a600: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a610: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a620: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a630: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a640: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a650: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a660: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a670: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a680: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a690: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a6a0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a6b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a6c0: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a6d0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a6e0: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a6f0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a700: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a710: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a720: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a730: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a740: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a750: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a760: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a770: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a780: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a790: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a7a0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a7b0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a7c0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
a7d0: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
a7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
a7f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
a800: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
a810: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
a820: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
a830: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
a840: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
a850: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
a860: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
a870: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a880: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
a890: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
a8a0: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
a8b0: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
a8c0: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
a8d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
a8e0: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
a8f0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
a900: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
a910: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
a920: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
a930: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
a940: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
a950: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a960: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a970: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a980: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a990: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a9a0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a9b0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a9c0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a9d0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a9e0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a9f0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
aa00: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
aa10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
aa20: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
aa30: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
aa40: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
aa50: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
aa60: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aa70: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
aa80: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
aa90: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
aaa0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
aab0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
aac0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
aad0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
aae0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
aaf0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
ab00: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
ab10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
ab20: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
ab30: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
ab40: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
ab50: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
ab60: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
ab70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ab80: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
ab90: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
aba0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
abb0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
abc0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
abd0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
abe0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
abf0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
ac00: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
ac10: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
ac20: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
ac30: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
ac40: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
ac50: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
ac60: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
ac70: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
ac80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
ac90: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
aca0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
acb0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
acc0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
acd0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
ace0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
acf0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
ad00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
ad10: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
ad20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
ad30: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
ad40: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
ad50: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
ad60: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
ad70: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
ad80: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
ad90: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
ada0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
adb0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
adc0: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
add0: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
ade0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
adf0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
ae00: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
ae10: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
ae20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae30: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ae40: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ae50: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
ae60: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ae70: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
ae80: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
ae90: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
aea0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
aeb0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
aec0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
aed0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
aee0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
aef0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
af00: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
af10: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
af20: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
af30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
af40: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
af50: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
af60: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
af70: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
af80: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
af90: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
afa0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
afb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
afc0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
afd0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
afe0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
aff0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b000: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b010: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b020: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b030: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b040: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
b050: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
b060: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
b070: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
b080: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
b090: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
b0a0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
b0b0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
b0c0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
b0d0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
b0e0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
b0f0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
b100: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
b110: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
b120: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
b130: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
b140: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
b150: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
b160: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
b170: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
b180: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
b190: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
b1a0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
b1b0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
b1c0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
b1d0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
b1e0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
b1f0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
b200: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
b210: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
b220: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
b230: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
b240: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
b250: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
b260: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
b270: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b280: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b290: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
b2a0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
b2b0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
b2c0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b2d0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
b2e0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
b2f0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b300: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b310: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b320: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b330: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b340: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b350: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b360: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b370: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b380: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b390: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b3a0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b3b0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b3c0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b3d0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b3e0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b3f0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b400: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b410: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b420: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b430: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b440: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b450: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b460: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b470: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b480: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b490: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b4a0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b4b0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b4c0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b4d0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b4e0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b4f0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b500: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b510: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b520: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b530: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b540: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b550: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b560: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b570: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b580: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b590: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b5a0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b5b0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b5c0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b5d0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b5e0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b5f0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b600: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b610: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b620: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b630: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b640: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b650: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b660: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b670: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b680: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b690: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b6a0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b6b0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b6c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b6d0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b6e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b6f0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b700: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b710: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b720: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b730: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b740: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b750: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b760: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b770: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b780: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b790: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b7a0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b7b0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b7c0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b7d0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b7e0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b7f0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b800: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b810: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b820: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b830: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b840: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b850: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b860: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b870: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b880: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b890: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b8a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b8b0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b8c0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b8d0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b8e0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b8f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b900: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b910: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b920: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b930: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b940: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b950: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b960: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b970: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b980: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b990: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b9a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b9b0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b9c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b9d0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b9e0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b9f0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
ba00: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
ba10: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
ba20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
ba30: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
ba40: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
ba50: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
ba60: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
ba70: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
ba80: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
ba90: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
baa0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
bab0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
bac0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
bad0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
bae0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
baf0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
bb00: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
bb10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
bb20: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
bb30: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
bb40: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
bb50: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
bb60: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
bb70: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
bb80: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
bb90: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
bba0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
bbb0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
bbc0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
bbd0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
bbe0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
bbf0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
bc00: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
bc10: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
bc20: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
bc30: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
bc40: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
bc50: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
bc60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bc70: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
bc80: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bc90: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
bca0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
bcb0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
bcc0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
bcd0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
bce0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
bcf0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
bd00: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
bd10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
bd20: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
bd30: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
bd40: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
bd50: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
bd60: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
bd70: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
bd80: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
bd90: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
bda0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bdb0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
bdc0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
bdd0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
bde0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
bdf0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
be00: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
be10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
be20: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
be30: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
be40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
be50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
be60: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
be70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
be80: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
be90: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bea0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
beb0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
bec0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bed0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bee0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bef0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bf00: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
bf10: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bf20: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bf30: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bf40: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bf50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf60: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bf70: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bf80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf90: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bfa0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bfb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bfc0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bfd0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bfe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bff0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
c000: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
c010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c020: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
c030: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
c040: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c050: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
c060: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
c070: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c080: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
c090: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
c0a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c0b0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
c0c0: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
c0d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
c0e0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
c0f0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
c100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
c110: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
c120: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
c130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
c140: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
c150: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
c160: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
c170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c180: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
c190: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c1a0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
c1b0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
c1c0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c1d0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
c1e0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
c1f0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c200: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
c210: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c220: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
c230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
c240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c250: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
c260: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
c270: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c280: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
c290: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23              27.#
c2a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c2b0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
c2c0: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 0a 2f  TER        28../
c2d0: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
c2e0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
c2f0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
c300: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c310: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c320: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c330: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
c340: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c350: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c360: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
c380: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c390: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c3a0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
c3b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c3c0: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
c3d0: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
c3e0: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
c3f0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
c400: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
c410: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
c420: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
c430: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
c440: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c450: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c460: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c470: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c480: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c490: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c4a0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c4b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c4c0: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c4d0: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c4e0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c4f0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c500: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c510: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c520: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c530: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c540: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
c550: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
c560: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c570: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c580: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
c590: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
c5a0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
c5b0: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
c5c0: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
c5d0: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
c5e0: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
c5f0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
c600: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
c610: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
c620: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
c630: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
c640: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
c650: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
c660: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
c670: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
c680: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
c690: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
c6a0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
c6b0: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
c6c0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
c6d0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
c6e0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
c6f0: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
c700: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
c710: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
c720: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
c730: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
c740: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
c750: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
c760: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
c770: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
c780: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
c790: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
c7a0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
c7b0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
c7c0: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
c7d0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
c7e0: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
c7f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
c800: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
c810: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
c820: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
c830: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
c840: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
c850: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
c860: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
c870: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
c880: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
c890: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
c8a0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
c8b0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
c8c0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
c8d0: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
c8e0: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
c8f0: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
c900: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
c910: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
c920: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
c930: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
c940: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
c950: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
c960: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
c970: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
c980: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
c990: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
c9a0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
c9b0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
c9c0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
c9d0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
c9e0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
c9f0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
ca00: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
ca10: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
ca20: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
ca30: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
ca40: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
ca50: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
ca60: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
ca70: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
ca80: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
ca90: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
caa0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
cab0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
cac0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
cad0: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
cae0: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
caf0: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
cb00: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
cb10: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
cb20: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
cb30: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
cb40: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
cb50: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
cb60: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
cb70: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
cb80: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
cb90: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
cba0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
cbb0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
cbc0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
cbd0: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
cbe0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
cbf0: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
cc00: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
cc10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
cc20: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
cc30: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
cc40: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
cc50: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
cc60: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
cc70: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
cc80: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
cc90: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
cca0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
ccb0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
ccc0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
ccd0: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
cce0: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
ccf0: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
cd00: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
cd10: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
cd20: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
cd30: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
cd40: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
cd50: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
cd60: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
cd70: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
cd80: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
cd90: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
cda0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
cdb0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
cdc0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
cdd0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
cde0: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
cdf0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ce00: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
ce10: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
ce20: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
ce30: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
ce40: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
ce50: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
ce60: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
ce70: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
ce80: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
ce90: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
cea0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
ceb0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
cec0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
ced0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cee0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
cef0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
cf00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
cf10: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
cf20: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
cf30: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
cf40: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
cf50: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
cf60: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
cf70: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
cf80: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
cf90: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
cfa0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
cfb0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
cfc0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
cfd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
cfe0: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
cff0: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
d000: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
d010: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
d020: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
d030: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
d040: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
d050: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
d060: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
d070: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
d080: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
d090: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
d0a0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
d0b0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
d0c0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
d0d0: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
d0e0: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
d0f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d100: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
d110: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
d130: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d140: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
d150: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d160: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
d170: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
d180: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
d190: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
d1a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d1b0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
d1c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d1d0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
d1e0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d1f0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
d200: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
d210: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
d220: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
d230: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
d240: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
d250: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
d260: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
d270: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
d280: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
d290: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
d2a0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
d2b0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
d2c0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
d2d0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
d2e0: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
d2f0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
d300: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
d310: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
d320: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
d330: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
d340: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
d350: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
d360: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
d370: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
d380: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
d390: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
d3a0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
d3b0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
d3c0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
d3d0: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
d3e0: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
d3f0: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
d400: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
d410: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
d420: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
d430: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d440: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d450: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d460: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d470: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
d480: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d490: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
d4a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
d4b0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
d4c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
d4d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d4e0: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
d4f0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
d500: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
d510: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
d520: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
d530: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d540: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
d550: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
d560: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
d570: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
d580: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
d590: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
d5a0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
d5b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d5c0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
d5d0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
d5e0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
d5f0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
d600: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
d610: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
d620: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
d630: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
d640: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
d650: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
d660: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
d670: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
d680: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
d690: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
d6a0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
d6b0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
d6c0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
d6d0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
d6e0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
d6f0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
d700: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
d710: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
d720: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
d730: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
d740: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
d750: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
d760: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
d770: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
d780: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
d790: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
d7a0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
d7b0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
d7c0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
d7d0: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
d7e0: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
d7f0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
d800: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
d810: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
d820: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
d830: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
d840: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
d850: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
d860: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
d870: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
d880: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
d890: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
d8a0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
d8b0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
d8c0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
d8d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
d8e0: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
d8f0: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
d900: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
d910: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
d920: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
d930: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d940: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
d950: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
d960: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
d970: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
d980: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
d990: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
d9a0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
d9b0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
d9c0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
d9d0: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
d9e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
d9f0: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
da00: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
da10: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
da20: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
da30: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
da40: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
da50: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
da60: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
da70: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
da80: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
da90: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
daa0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
dab0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
dac0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
dad0: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
dae0: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
daf0: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
db00: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
db10: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
db20: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
db30: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
db40: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
db50: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
db60: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
db70: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
db80: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
db90: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
dba0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
dbb0: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
dbc0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
dbd0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
dbe0: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
dbf0: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
dc00: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
dc10: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
dc20: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
dc30: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
dc40: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
dc50: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
dc60: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
dc70: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
dc80: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
dc90: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
dca0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
dcb0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
dcc0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
dcd0: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
dce0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
dcf0: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
dd00: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
dd10: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
dd20: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
dd30: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
dd40: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
dd50: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
dd60: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
dd70: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
dd80: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
dd90: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
dda0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
ddb0: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
ddc0: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
ddd0: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
dde0: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
ddf0: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
de00: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
de10: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
de20: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
de30: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
de40: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
de50: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
de60: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
de70: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
de80: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
de90: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
dea0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
deb0: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
dec0: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
ded0: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
dee0: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
def0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
df00: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
df10: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
df20: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
df30: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
df40: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
df50: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
df60: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
df70: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
df80: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
df90: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
dfa0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
dfb0: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
dfc0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
dfd0: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
dfe0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
dff0: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
e000: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
e010: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
e020: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
e030: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
e040: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
e050: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
e060: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
e070: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
e080: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
e090: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
e0a0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
e0b0: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
e0c0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
e0d0: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
e0e0: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
e0f0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
e100: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
e110: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
e120: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
e130: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
e140: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
e150: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
e160: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
e170: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
e180: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
e190: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
e1a0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
e1b0: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
e1c0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
e1d0: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
e1e0: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
e1f0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
e200: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
e210: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
e220: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
e230: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
e240: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
e250: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
e260: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
e270: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
e280: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
e290: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
e2a0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
e2b0: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
e2c0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e2d0: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
e2e0: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
e2f0: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
e300: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
e310: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e320: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
e330: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
e340: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
e350: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
e360: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
e370: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
e380: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
e390: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
e3a0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
e3b0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
e3c0: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
e3d0: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
e3e0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
e3f0: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
e400: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
e410: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
e420: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
e430: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e440: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
e450: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
e460: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
e470: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
e480: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
e490: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
e4a0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
e4b0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
e4c0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
e4d0: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
e4e0: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
e4f0: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
e500: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
e510: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
e520: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
e530: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
e540: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
e550: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
e560: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
e570: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
e580: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
e590: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
e5a0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
e5b0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
e5c0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
e5d0: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
e5e0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e5f0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e600: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
e610: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
e620: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
e630: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
e640: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e650: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e660: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
e670: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
e680: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
e690: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e6a0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
e6b0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
e6c0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
e6d0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
e6e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e6f0: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
e700: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
e710: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
e720: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e730: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
e740: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
e750: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
e760: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
e770: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
e780: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
e790: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
e7a0: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
e7b0: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
e7c0: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
e7d0: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
e7e0: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
e7f0: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
e800: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
e810: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
e820: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
e830: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
e840: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
e850: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
e860: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
e870: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
e880: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
e890: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
e8a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e8b0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
e8c0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e8d0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e8e0: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
e8f0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e900: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
e910: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
e920: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
e930: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
e940: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
e950: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
e960: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
e970: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
e980: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
e990: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e9a0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e9b0: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
e9c0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e9d0: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
e9e0: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
e9f0: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
ea00: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
ea10: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
ea20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ea30: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ea40: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
ea50: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
ea60: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
ea70: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
ea80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ea90: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
eaa0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
eab0: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
eac0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ead0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
eae0: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
eaf0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
eb00: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
eb10: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
eb20: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
eb30: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
eb40: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
eb50: 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  ended in future 
eb60: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
eb70: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
eb80: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
eb90: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
eba0: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
ebb0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ebc0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ebd0: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
ebe0: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
ebf0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
ec00: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
ec10: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
ec20: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
ec30: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
ec40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
ec50: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
ec60: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
ec70: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
ec80: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
ec90: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
eca0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
ecb0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
ecc0: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
ecd0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
ece0: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
ecf0: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
ed00: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
ed10: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
ed20: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
ed30: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
ed40: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
ed50: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
ed60: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
ed70: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
ed80: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
ed90: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
eda0: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
edb0: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
edc0: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
edd0: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
ede0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
edf0: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
ee00: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
ee10: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
ee20: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ee30: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
ee40: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
ee50: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
ee60: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
ee70: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
ee80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ee90: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
eea0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
eeb0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
eec0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
eed0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
eee0: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
eef0: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
ef00: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
ef10: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
ef20: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
ef30: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
ef40: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
ef50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
ef60: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
ef70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ef80: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
ef90: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
efa0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
efb0: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
efc0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
efd0: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
efe0: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
eff0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
f000: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
f010: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
f020: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
f030: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
f040: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
f050: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
f060: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
f070: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f080: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
f090: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
f0a0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
f0b0: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
f0c0: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
f0d0: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
f0e0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
f0f0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
f100: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
f110: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
f120: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
f130: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f140: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
f150: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
f160: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
f170: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
f180: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
f190: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f1a0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
f1b0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
f1c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
f1d0: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
f1e0: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
f1f0: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
f200: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
f210: 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
f220: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
f230: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
f240: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f250: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
f260: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
f270: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
f280: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
f290: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
f2a0: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
f2b0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f2c0: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
f2d0: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
f2e0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
f2f0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
f300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
f310: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
f320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f330: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
f340: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
f350: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
f360: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
f370: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
f380: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
f390: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
f3a0: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
f3b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
f3c0: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
f3d0: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
f3e0: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
f3f0: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
f400: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
f410: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
f420: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
f430: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
f440: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
f450: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
f460: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
f470: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
f480: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
f490: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
f4a0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
f4b0: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
f4c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f4d0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f4e0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
f4f0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
f500: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
f510: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
f520: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
f530: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
f540: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
f550: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
f560: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
f570: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
f580: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
f590: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
f5a0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f5b0: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
f5c0: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
f5d0: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
f5e0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
f5f0: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
f600: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
f610: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
f620: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
f630: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
f640: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f650: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f660: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
f670: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
f680: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
f690: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f6a0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
f6b0: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
f6c0: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
f6d0: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
f6e0: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
f6f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f700: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f710: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
f720: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f730: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
f740: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
f750: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
f760: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f770: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
f780: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
f790: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
f7a0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
f7b0: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
f7c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f7d0: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
f7e0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
f7f0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
f800: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
f810: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f820: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
f830: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f840: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
f850: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
f860: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f870: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
f880: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
f890: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
f8a0: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
f8b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f8c0: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
f8d0: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
f8e0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
f8f0: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
f900: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
f910: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
f920: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
f930: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
f940: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
f950: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
f960: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
f970: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
f980: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
f990: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f9a0: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
f9b0: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
f9c0: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
f9d0: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
f9e0: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
f9f0: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
fa00: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
fa10: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
fa20: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
fa30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa40: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
fa50: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fa60: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
fa70: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fa80: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
fa90: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
faa0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
fab0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fac0: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
fad0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
fae0: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
faf0: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
fb00: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
fb10: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
fb20: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
fb30: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
fb40: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
fb50: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
fb60: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
fb70: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
fb80: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
fb90: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
fba0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
fbb0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
fbc0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fbd0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fbe0: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
fbf0: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
fc00: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
fc10: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
fc20: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
fc30: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
fc40: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
fc50: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
fc60: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
fc70: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
fc80: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
fc90: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
fca0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fcb0: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
fcc0: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
fcd0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
fce0: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
fcf0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
fd00: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
fd10: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
fd20: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
fd30: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
fd40: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
fd50: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
fd60: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
fd70: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
fd80: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
fd90: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
fda0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
fdb0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
fdc0: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
fdd0: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
fde0: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
fdf0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fe00: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
fe10: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
fe20: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fe30: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
fe40: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
fe50: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
fe60: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
fe70: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
fe80: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
fe90: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
fea0: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
feb0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
fec0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fed0: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
fee0: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
fef0: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
ff00: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
ff10: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
ff20: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
ff30: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
ff40: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
ff50: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
ff60: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
ff70: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
ff80: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
ff90: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
ffa0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
ffb0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
ffc0: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
ffd0: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
ffe0: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
fff0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
10000 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10010 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
10020 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
10030 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
10040 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
10050 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
10060 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
10070 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
10080 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
10090 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
100a0 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
100b0 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
100c0 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
100d0 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
100e0 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
100f0 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
10100 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
10110 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
10120 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
10130 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
10140 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
10150 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
10160 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10170 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
10180 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
10190 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
101a0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
101b0 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
101c0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
101d0 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
101e0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
101f0 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
10200 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10210 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
10220 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
10230 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
10240 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
10250 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
10260 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
10270 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
10280 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
10290 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
102a0 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
102b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
102c0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
102d0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
102e0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
102f0 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
10300 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
10310 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
10320 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
10330 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
10340 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
10350 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
10360 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
10370 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
10380 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
10390 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
103a0 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
103b0 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
103c0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
103d0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
103e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
103f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10400 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
10410 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
10420 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10430 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
10440 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
10450 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
10460 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
10470 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
10480 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
10490 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
104a0 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
104b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
104c0 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
104d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
104e0 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
104f0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10500 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
10510 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
10520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10530 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
10540 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
10550 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10560 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
10570 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
10580 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
10590 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
105a0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
105b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
105c0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
105d0 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
105e0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
105f0 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
10600 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
10610 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
10620 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
10630 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
10640 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
10650 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
10660 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
10670 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
10680 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
10690 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
106a0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
106b0 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  <b>The sqlite3_c
106c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
106d0 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
106e0 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61  afe. The applica
106f0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
10700 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
10710 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
10720 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
10730 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
10740 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
10750 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
10760 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  nning.</b>.**.**
10770 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
10780 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a  fig() interface.
10790 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
107a0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
107b0 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
107c0 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
107d0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
107e0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
107f0 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
10800 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10810 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
10820 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
10830 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
10840 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
10850 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
10860 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10870 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
10880 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
10890 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
108a0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
108b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
108c0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
108d0 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
108e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
108f0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
10900 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
10910 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
10920 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10930 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10940 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
10950 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
10960 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10970 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
10980 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
10990 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
109a0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
109b0 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
109c0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
109d0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
109e0 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
109f0 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
10a00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10a10 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
10a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10a30 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
10a40 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
10a50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
10a60 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
10a70 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
10a80 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
10a90 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
10aa0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
10ab0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
10ac0 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
10ad0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
10ae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
10af0 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
10b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10b10 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
10b20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
10b30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
10b40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
10b50 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
10b60 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10b70 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
10b80 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10b90 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
10ba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10bb0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
10bc0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
10bd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10be0 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
10bf0 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
10c00 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
10c10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10c20 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
10c30 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10c40 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
10c50 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10c60 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
10c70 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
10c80 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
10c90 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10ca0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10cb0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
10cc0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
10cd0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
10ce0 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
10cf0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10d00 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
10d10 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10d20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10d30 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
10d40 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
10d50 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
10d60 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
10d70 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10d80 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
10d90 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
10da0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10db0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
10dc0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
10dd0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10de0 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
10df0 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
10e00 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10e10 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10e20 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
10e30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10e40 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
10e50 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
10e60 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
10e70 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
10e80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10e90 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10ea0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10eb0 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10ec0 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10ed0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10ee0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
10ef0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10f00 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
10f10 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10f20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10f30 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
10f40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10f50 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
10f60 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
10f70 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10f80 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10f90 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10fa0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10fb0 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10fc0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10fd0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10ff0 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
11000 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
11010 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
11020 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
11030 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
11040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
11050 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
11060 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
11070 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
11080 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
11090 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
110a0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
110b0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
110c0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
110d0 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
110e0 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
110f0 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
11100 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
11110 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
11120 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
11130 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
11140 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
11150 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
11160 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
11170 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
11180 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
11190 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
111a0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
111b0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
111c0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
111d0 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
111e0 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
111f0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
11200 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11210 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
11220 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
11230 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
11240 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
11250 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
11260 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
11270 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
11280 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
11290 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
112a0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
112b0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
112c0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
112d0 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
112e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
112f0 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
11300 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
11310 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
11320 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
11330 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
11340 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
11350 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
11360 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
11370 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
11380 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
11390 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
113a0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
113b0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
113c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
113d0 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
113e0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
113f0 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
11400 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
11410 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
11420 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
11430 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
11440 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
11450 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
11460 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
11470 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
11480 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
11490 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
114a0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
114b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
114c0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
114d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
114e0 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
114f0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11500 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
11510 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
11520 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
11530 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
11540 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
11550 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
11560 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
11570 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
11580 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
11590 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
115a0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
115b0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
115c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
115d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
115e0 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
115f0 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
11600 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
11610 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
11620 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
11630 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
11640 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
11650 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
11660 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
11670 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11680 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
11690 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
116a0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
116b0 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
116c0 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
116d0 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
116e0 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
116f0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11700 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
11710 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
11720 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11730 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
11740 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
11750 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
11760 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
11770 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
11780 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
11790 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
117a0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
117b0 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
117c0 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
117d0 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
117e0 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
117f0 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
11800 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
11810 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
11820 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
11830 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
11840 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
11850 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11860 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
11870 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
11880 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
11890 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
118a0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
118b0 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
118c0 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
118d0 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
118e0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
118f0 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
11900 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
11910 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
11920 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
11930 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11940 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
11950 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
11960 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
11970 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
11980 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11990 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
119a0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
119b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
119c0 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
119d0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
119e0 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
119f0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11a00 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11a10 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11a20 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
11a30 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
11a40 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
11a50 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
11a60 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
11a70 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
11a80 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11a90 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11aa0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11ab0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11ac0 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11ad0 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11ae0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11af0 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11b00 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11b10 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11b20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
11b30 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
11b40 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
11b50 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
11b60 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
11b70 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
11b80 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
11b90 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
11ba0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11bb0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11bc0 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11bd0 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11be0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11bf0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11c00 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11c10 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11c20 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
11c30 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
11c40 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
11c50 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
11c60 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11c70 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
11c80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11c90 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11ca0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11cb0 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11cc0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11cd0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11ce0 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11d00 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11d10 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11d20 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
11d30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11d40 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
11d50 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
11d60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11d70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
11d80 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11d90 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11da0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11db0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11dc0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11dd0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
11de0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11df0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11e00 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
11e10 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11e20 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
11e30 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
11e40 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
11e50 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
11e60 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
11e70 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
11e80 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
11e90 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
11ea0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11eb0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
11ec0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
11ed0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
11ee0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
11ef0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
11f00 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11f10 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11f20 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
11f30 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11f40 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
11f50 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
11f60 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
11f70 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
11f80 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11f90 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
11fa0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11fb0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11fc0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11fd0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11fe0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11ff0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12000 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12010 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12020 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12030 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
12040 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
12050 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
12060 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
12070 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
12080 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
12090 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
120a0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
120b0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
120c0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
120d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
120e0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
120f0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12100 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12110 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12120 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12130 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12140 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
12150 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
12160 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
12170 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
12180 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
12190 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
121a0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
121b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
121c0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
121d0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
121e0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
121f0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12200 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12210 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12220 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
12230 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12240 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
12250 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
12260 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
12270 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12280 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
12290 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
122a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
122b0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
122c0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
122d0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
122e0 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
122f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12300 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12310 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12320 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
12330 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
12340 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
12350 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
12360 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12370 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12380 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12390 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
123a0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
123b0 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
123c0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
123d0 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
123e0 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
123f0 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
12400 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
12410 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
12420 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
12430 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12440 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
12450 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
12460 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12470 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12480 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12490 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
124a0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
124b0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
124c0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
124d0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
124e0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
124f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12500 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12510 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12520 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12530 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12540 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
12550 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
12560 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
12570 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12580 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12590 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
125a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
125b0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
125c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
125d0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
125e0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
125f0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12600 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12610 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12620 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
12630 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
12640 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
12650 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
12660 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
12670 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
12680 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
12690 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
126a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
126b0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
126c0 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
126d0 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
126e0 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
126f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12700 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
12710 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
12720 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
12730 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
12740 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
12750 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12760 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
12770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
12780 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
12790 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
127a0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
127b0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
127c0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
127d0 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
127e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
127f0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
12800 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
12810 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
12820 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12830 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12840 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12850 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12860 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12870 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12880 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
12890 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
128a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
128b0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
128c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
128d0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
128e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
128f0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12900 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12910 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
12920 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12930 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12940 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12950 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12960 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12970 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
12980 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
12990 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
129a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
129b0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
129c0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
129d0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
129e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
129f0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12a00 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
12a10 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12a20 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12a30 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12a40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12a50 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
12a60 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
12a70 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12a80 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
12a90 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12aa0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12ab0 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
12ac0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
12ad0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
12ae0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12af0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
12b00 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
12b10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12b20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
12b30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12b40 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12b50 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12b60 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12b70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12b80 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12b90 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
12ba0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12bb0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12bc0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
12bd0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12be0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12bf0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12c00 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
12c10 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12c20 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12c30 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12c40 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
12c50 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
12c60 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12c70 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12c80 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12c90 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12ca0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12cb0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12cc0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12cd0 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12ce0 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12cf0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12d00 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12d10 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12d20 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12d30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12d40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
12d50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12d60 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
12d70 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12d90 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
12da0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
12db0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
12dc0 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
12dd0 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
12de0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
12df0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
12e00 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
12e10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12e20 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
12e30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12e40 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
12e50 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
12e60 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
12e70 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
12e80 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
12e90 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
12ea0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12eb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
12ec0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12ed0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
12ee0 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
12ef0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
12f00 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
12f10 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12f20 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
12f30 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
12f40 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
12f50 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12f60 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
12f70 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
12f80 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
12f90 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
12fa0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
12fb0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
12fc0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
12fd0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12fe0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
12ff0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
13000 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13010 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13020 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
13030 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
13040 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13060 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70  CRATCH option sp
13070 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
13080 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
13090 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
130a0 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63  n use for scratc
130b0 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65  h memory.  ^(The
130c0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
130d0 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c  uments.** to SQL
130e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
130f0 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  CH:  A pointer a
13100 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13110 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
13120 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
13130 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13140 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
13150 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
13160 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
13170 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
13180 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
13190 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
131a0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
131b0 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20  s (N).)^.** The 
131c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
131d0 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
131e0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
131f0 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
13200 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
13210 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13220 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
13230 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74  l not use more t
13240 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
13250 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
13260 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ad..** ^SQLite w
13270 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
13280 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
13290 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
132a0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
132b0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
132c0 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53  e size..** ^If S
132d0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
132e0 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
132f0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
13300 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
13310 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
13320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13330 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
13340 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13350 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
13360 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
13370 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
13380 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
13390 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
133a0 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
133b0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
133c0 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
133d0 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
133e0 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
133f0 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
13400 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
13410 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
13420 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
13430 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
13440 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
13450 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
13460 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
13470 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
13480 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
13490 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
134a0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
134b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
134c0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
134d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
134e0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
134f0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
13500 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13510 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
13520 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f  fies a memory po
13530 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  ol.** that SQLit
13540 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68  e can use for th
13550 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
13560 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
13570 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63  efault page.** c
13580 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13590 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
135a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
135b0 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69  ion is a no-op i
135c0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
135d0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
135e0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
135f0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
13600 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
13610 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
13620 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
13630 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
13640 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
13650 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f  _PAGECACHE: A po
13660 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79  inter to.** 8-by
13670 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  te aligned memor
13680 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69  y (pMem), the si
13690 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
136a0 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c  cache line (sz),
136b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  .** and the numb
136c0 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65  er of cache line
136d0 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
136e0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
136f0 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
13700 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
13710 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
13720 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
13730 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35  ween 512 and 655
13740 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78  36) plus some ex
13750 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61  tra bytes for ea
13760 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
13770 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  r.  ^The number 
13780 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e  of extra bytes n
13790 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67  eeded by the pag
137a0 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20  e header.** can 
137b0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
137c0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ing [SQLITE_CONF
137d0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
137e0 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d  ..** ^It is harm
137f0 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
13800 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
13810 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ry,.** for the s
13820 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  z parameter to b
13830 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65  e larger than ne
13840 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d  cessary.  The pM
13850 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  em.** argument m
13860 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
13870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
13880 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13890 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
138a0 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  d block of memor
138b0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  y of at least sz
138c0 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77  *N bytes, otherw
138d0 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e  ise.** subsequen
138e0 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  t behavior is un
138f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65  defined..** ^Whe
13900 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55  n pMem is not NU
13910 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
13920 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68  strive to use th
13930 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
13940 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20  d.** to satisfy 
13950 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73  page cache needs
13960 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74  , falling back t
13970 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
13980 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67  c()] if.** a pag
13990 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20  e cache line is 
139a0 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62  larger than sz b
139b0 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f  ytes or if all o
139c0 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65  f the pMem buffe
139d0 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65  r.** is exhauste
139e0 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69  d..** ^If pMem i
139f0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
13a00 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65  non-zero, then e
13a10 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
13a20 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20  nection.** does 
13a30 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20  an initial bulk 
13a40 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70  allocation for p
13a50 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13a60 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
13a70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66  3_malloc()] suff
13a80 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63  icient for N cac
13a90 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73  he lines if N is
13aa0 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20   positive or.** 
13ab0 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73  of -1024*N bytes
13ac0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
13ad0 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f  e, . ^If additio
13ae0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
13af0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
13b00 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
13b10 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
13b20 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c  e initial.** all
13b30 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51  ocation, then SQ
13b40 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
13b50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13b60 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65  separately for e
13b70 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  ach.** additiona
13b80 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f  l cache line. </
13b90 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13ba0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
13bb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13bc0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
13bd0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13be0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
13bf0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
13c00 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
13c10 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51  ffer .** that SQ
13c20 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f  Lite will use fo
13c30 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
13c40 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
13c50 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20  cation needs.** 
13c60 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
13c70 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51  vided for by [SQ
13c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13c90 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c  TCH] and.** [SQL
13ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13cb0 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53  ACHE]..** ^The S
13cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13cd0 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  P option is only
13ce0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
13cf0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13d00 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20  .** with either 
13d10 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13d20 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49  EMSYS3] or [SQLI
13d30 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
13d40 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  5] and returns.*
13d50 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
13d60 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65   if invoked othe
13d70 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65  rwise..** ^There
13d80 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
13d90 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
13da0 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41  ONFIG_HEAP:.** A
13db0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
13dc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
13dd0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
13de0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
13df0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
13e00 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
13e10 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13e20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
13e30 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
13e40 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
13e50 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
13e60 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
13e70 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
13e80 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
13e90 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
13ea0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
13eb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
13ec0 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
13ed0 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
13ee0 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
13ef0 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
13f00 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
13f10 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
13f20 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  L then the alter
13f30 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
13f40 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
13f50 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
13f60 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
13f70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13f80 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
13f90 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
13fa0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
13fb0 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
13fc0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
13fd0 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
13fe0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
13ff0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
14000 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
14010 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
14020 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
14030 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
14040 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
14050 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
14060 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14070 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
14080 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
14090 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
140a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
140b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
140c0 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
140d0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
140e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
140f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14100 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14110 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69  hich is a.** poi
14120 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14130 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14140 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14150 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
14160 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
14170 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74  ecifies alternat
14180 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
14190 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
141a0 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c  be used.** in pl
141b0 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f  ace the mutex ro
141c0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
141d0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
141e0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
141f0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
14200 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14210 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14220 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
14230 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
14240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
14250 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
14260 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14270 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14280 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14290 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
142a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
142b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
142c0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
142d0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
142e0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
142f0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14300 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14310 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14320 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14330 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14340 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
14350 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
14360 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
14370 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
14380 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14390 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
143a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
143b0 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
143c0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
143d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
143e0 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
143f0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14400 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14410 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14420 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14430 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
14440 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14450 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
14460 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14470 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
14480 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
14490 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
144a0 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
144b0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
144c0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
144d0 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
144e0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
144f0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
14500 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
14510 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
14520 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
14530 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
14540 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
14550 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
14560 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
14570 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14580 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14590 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
145a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
145b0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
145c0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
145d0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
145e0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
145f0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
14600 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
14610 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
14620 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14630 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14640 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14650 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
14660 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
14670 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
14680 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
14690 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
146a0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74  _LOOKASIDE]] <dt
146b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
146c0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
146d0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
146e0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
146f0 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  IDE option takes
14700 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
14710 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hat determine.**
14720 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a   the default siz
14730 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
14740 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64  emory on each [d
14750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14760 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
14770 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
14780 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
14790 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
147a0 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
147b0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
147c0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
147d0 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
147e0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
147f0 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c  ection.)^  ^(SQL
14800 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14810 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65  SIDE.** sets the
14820 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
14830 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
14840 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
14850 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
14860 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71  ** option to [sq
14870 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14880 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
14890 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
148a0 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
148b0 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
148c0 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
148d0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
148e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
148f0 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
14900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14910 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14920 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14930 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
14940 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14950 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14960 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
14970 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
14980 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14990 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
149a0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
149b0 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66  es.** the interf
149c0 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  ace to a custom 
149d0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
149e0 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  mentation.)^.** 
149f0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
14a00 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
14a10 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14a20 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64  ods2] object.</d
14a30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14a40 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14a50 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
14a60 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14a70 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
14a80 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14a90 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f  FIG_GETPCACHE2 o
14aa0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14ab0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14ac0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
14ad0 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74  ter to an [sqlit
14ae0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14af0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
14b00 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a  ite copies of.**
14b10 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67   the current pag
14b20 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14b30 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
14b40 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
14b50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14b60 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
14b70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
14b80 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
14b90 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14ba0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
14bb0 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
14bc0 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
14bd0 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
14be0 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
14bf0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
14c00 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
14c10 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
14c20 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
14c30 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
14c40 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
14c50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
14c60 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
14c70 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
14c80 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
14c90 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
14ca0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
14cb0 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
14cc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
14cd0 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
14ce0 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
14cf0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
14d00 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
14d10 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
14d20 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
14d30 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
14d40 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
14d50 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
14d60 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
14d70 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
14d80 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
14d90 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
14da0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
14db0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14dc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
14dd0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
14de0 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
14df0 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
14e00 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
14e10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14e20 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
14e30 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
14e40 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
14e50 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14e60 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
14e70 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
14e80 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
14e90 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
14ea0 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
14eb0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
14ec0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
14ed0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
14ee0 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
14ef0 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
14f00 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
14f10 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
14f20 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
14f30 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
14f40 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
14f50 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
14f60 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
14f70 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
14f80 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
14f90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
14fa0 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
14fb0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
14fc0 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
14fd0 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
14fe0 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
14ff0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15000 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15010 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
15020 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
15030 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15040 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
15060 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49  * <dd>^(The SQLI
15070 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70  TE_CONFIG_URI op
15080 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15090 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
150a0 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20  type int..** If 
150b0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55  non-zero, then U
150c0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
150d0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
150e0 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
150f0 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68  r is zero,.** th
15100 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
15110 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
15120 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20  bled.)^ ^If URI 
15130 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15140 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c  ally.** enabled,
15150 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70   all filenames p
15160 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
15170 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
15180 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a  te3_open_v2()],.
15190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
151a0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
151b0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
151c0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
151d0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
151e0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
151f0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
15200 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
15210 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
15220 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
15230 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
15240 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
15250 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
15260 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
15270 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
15280 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
15290 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
152a0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
152b0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
152c0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
152d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
152e0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
152f0 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
15300 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
15310 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
15320 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
15330 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
15340 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
15350 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15360 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
15370 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
15380 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15390 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
153a0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
153b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
153c0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
153d0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
153e0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
153f0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f  ING_INDEX_SCAN o
15400 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15410 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20  ngle integer.** 
15420 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
15430 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
15440 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
15450 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
15460 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
15470 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15480 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15490 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
154a0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
154b0 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  zer..** ^The def
154c0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20  ault setting is 
154d0 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79  determined.** by
154e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c   the [SQLITE_ALL
154f0 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  OW_COVERING_INDE
15500 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d  X_SCAN] compile-
15510 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20  time option, or 
15520 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68  is "on".** if th
15530 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
15540 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  option is omitte
15550 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74  d..** The abilit
15560 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  y to disable the
15570 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
15580 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
15590 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a  l table scans.**
155a0 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65   is because some
155b0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64   incorrectly cod
155c0 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63  ed legacy applic
155d0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c  ations might mal
155e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e  function.** when
155f0 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
15600 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50  n is enabled.  P
15610 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69  roviding the abi
15620 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62  lity to.** disab
15630 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  le the optimizat
15640 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f  ion allows the o
15650 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c  lder, buggy appl
15660 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20  ication code to 
15670 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20  work.** without 
15680 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68  change even with
15690 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
156a0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
156b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
156c0 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49  _PCACHE]] [[SQLI
156d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
156e0 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  CHE]].** <dt>SQL
156f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15700 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e  E and SQLITE_CON
15710 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a  FIG_GETPCACHE.**
15720 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69   <dd> These opti
15730 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65  ons are obsolete
15740 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20   and should not 
15750 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63  be used by new c
15760 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65  ode..** They are
15770 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
15780 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15790 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f  ility but are no
157a0 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64  w no-ops..** </d
157b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
157c0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d  E_CONFIG_SQLLOG]
157d0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
157e0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a  CONFIG_SQLLOG.**
157f0 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
15800 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15810 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20  le if sqlite is 
15820 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
15830 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
15840 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d  BLE_SQLLOG] pre-
15850 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
15860 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72  defined. The fir
15870 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  st argument shou
15880 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74  ld.** be a point
15890 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  er to a function
158a0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29   of type void(*)
158b0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
158c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
158d0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
158e0 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79   should be of ty
158f0 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20  pe (void*). The 
15900 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
15910 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61  ked by the libra
15920 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73  ry.** in three s
15930 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74  eparate circumst
15940 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65  ances, identifie
15950 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70  d by the value p
15960 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
15970 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15980 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  . If the fourth 
15990 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20  parameter is 0, 
159a0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
159b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
159c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
159d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61  cond argument ha
159e0 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e  s just been open
159f0 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72  ed. The third ar
15a00 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73  gument.** points
15a10 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e   to a buffer con
15a20 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65  taining the name
15a30 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74   of the main dat
15a40 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74  abase file. If t
15a50 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15a60 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65  ameter is 1, the
15a70 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
15a80 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69  ent that the thi
15a90 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
15aa0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75  points to has ju
15ab0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64  st been executed
15ac0 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75  . Or, if the fou
15ad0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15ae0 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20   2, then.** the 
15af0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67  connection being
15b00 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
15b10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15b20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e  is being closed.
15b30 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   The.** third pa
15b40 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65  rameter is passe
15b50 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63  d NULL In this c
15b60 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ase.  An example
15b70 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a   of using this.*
15b80 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15b90 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65  option can be se
15ba0 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f  en in the "test_
15bb0 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65  sqllog.c" source
15bc0 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20   file in.** the 
15bd0 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65  canonical SQLite
15be0 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64   source tree.</d
15bf0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15c00 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15c10 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
15c20 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15c30 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49  IZE.** <dd>^SQLI
15c40 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15c50 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
15c60 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
15c70 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
15c80 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
15c90 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
15ca0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
15cb0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
15cc0 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
15cd0 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
15ce0 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
15cf0 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
15d00 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  mit..** ^The def
15d10 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e  ault setting can
15d20 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62   be overridden b
15d30 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  y each database 
15d40 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
15d50 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b  .** either the [
15d60 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
15d70 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79  ] command, or by
15d80 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
15d90 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
15da0 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74  _SIZE] file cont
15db0 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69  rol.  ^(The maxi
15dc0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
15dd0 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65   size.** will be
15de0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
15df0 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79  ted if necessary
15e00 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73   so that it does
15e10 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a   not exceed the.
15e20 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
15e30 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a  maximum mmap siz
15e40 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  e set by the.** 
15e50 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50  [SQLITE_MAX_MMAP
15e60 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SIZE] compile-t
15e70 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a  ime option.)^.**
15e80 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75   ^If either argu
15e90 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74  ment to this opt
15ea0 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ion is negative,
15eb0 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d   then that argum
15ec0 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65  ent is.** change
15ed0 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65  d to its compile
15ee0 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a  -time default..*
15ef0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15f00 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15f10 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
15f20 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15f30 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64  _HEAPSIZE.** <dd
15f40 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
15f50 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15f60 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  ZE option is onl
15f70 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
15f80 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
15f90 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
15fa0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
15fb0 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20  E_WIN32_MALLOC] 
15fc0 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
15fd0 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20  cro.** defined. 
15fe0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  ^SQLITE_CONFIG_W
15ff0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
16000 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
16010 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
16020 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
16030 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
16040 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
16050 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a  eated heap..**.*
16060 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16070 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
16080 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16090 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
160a0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
160b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
160c0 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
160d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
160e0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
160f0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
16100 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
16110 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
16120 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
16130 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
16140 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
16150 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
16160 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
16170 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16180 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
16190 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
161a0 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
161b0 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
161c0 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
161d0 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
161e0 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
161f0 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
16200 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16210 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
16220 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16230 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
16240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16250 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
16260 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
16270 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
16280 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
16290 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
162a0 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
162b0 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
162c0 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
162d0 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
162e0 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
162f0 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
16300 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
16310 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
16320 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
16330 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
16340 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
16350 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
16360 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
16370 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
16380 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
16390 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
163a0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
163b0 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
163c0 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
163d0 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
163e0 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
163f0 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
16400 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
16410 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
16420 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
16430 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
16440 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
16450 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16460 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
16470 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  LL]].** <dt>SQLI
16480 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
16490 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e  NL_SPILL.** <dd>
164a0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
164b0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
164c0 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  L option takes a
164d0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
164e0 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d  r which.** becom
164f0 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e  es the [statemen
16500 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c  t journal] spill
16510 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f  -to-disk thresho
16520 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d  ld.  .** [Statem
16530 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72  ent journals] ar
16540 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  e held in memory
16550 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a   until their siz
16560 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20  e (in bytes).** 
16570 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72  exceeds this thr
16580 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68  eshold, at which
16590 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20   point they are 
165a0 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e  written to disk.
165b0 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68  .** Or if the th
165c0 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73  reshold is -1, s
165d0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
165e0 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c  s are always hel
165f0 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79  d.** exclusively
16600 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   in memory..** S
16610 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d  ince many statem
16620 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76  ent journals nev
16630 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c  er become large,
16640 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69   setting the spi
16650 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20  ll.** threshold 
16660 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20  to a value such 
16670 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65  as 64KiB can gre
16680 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20  atly reduce the 
16690 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f  amount of.** I/O
166a0 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70   required to sup
166b0 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72  port statement r
166c0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  ollback..** The 
166d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
166e0 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  r this setting i
166f0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
16700 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
16710 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63  TMTJRNL_SPILL] c
16720 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16730 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  on..** </dl>.*/.
16740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16750 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
16760 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
16770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16780 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
16790 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
167a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
167b0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
167c0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
167d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
167e0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
167f0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
16800 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
16810 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16820 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
16830 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
16840 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16850 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16870 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
16880 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
16890 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
168a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
168b0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
168c0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
168d0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
168e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
168f0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
16900 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16910 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
16920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16930 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16940 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
16950 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
16960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16970 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
16980 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16990 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
169a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
169b0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
169c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
169d0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
169e0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
169f0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
16a00 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
16a10 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
16a20 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
16a30 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16a40 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
16a50 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16a70 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
16a80 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16aa0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
16ab0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
16ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16ad0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
16ae0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
16af0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16b10 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
16b20 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16b40 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
16b50 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
16b60 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
16b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16b80 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
16b90 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
16ba0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
16bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16bc0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
16bd0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
16be0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
16bf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16c00 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
16c10 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
16c20 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16c40 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
16c50 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
16c60 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
16c70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16c80 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16c90 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
16ca0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
16cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16cc0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
16cd0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
16ce0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
16cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16d00 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
16d10 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
16d20 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
16d30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d40 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52  TE_CONFIG_STMTJR
16d50 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36  NL_SPILL      26
16d60 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
16d70 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
16d80 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
16d90 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
16da0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
16db0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
16dc0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
16dd0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
16de0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16df0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
16e00 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
16e10 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16e20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
16e30 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
16e40 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
16e50 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
16e60 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
16e70 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
16e80 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
16e90 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
16ea0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16eb0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
16ec0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
16ed0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
16ee0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
16ef0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
16f00 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16f10 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
16f20 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
16f30 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
16f40 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
16f50 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
16f60 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
16f70 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
16f80 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
16f90 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
16fa0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
16fb0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
16fc0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
16fd0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
16fe0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16ff0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
17000 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17010 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
17020 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17030 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
17040 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
17050 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
17060 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
17070 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
17080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17090 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
170a0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
170b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
170c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
170d0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
170e0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
170f0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
17100 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
17110 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
17120 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17130 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
17140 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17150 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
17160 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
17170 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
17180 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
17190 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
171a0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
171b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
171c0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
171d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
171e0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
171f0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
17200 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
17210 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
17220 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
17230 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
17240 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
17250 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
17260 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
17270 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
17280 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
17290 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
172a0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
172b0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
172c0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
172d0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
172e0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
172f0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
17300 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
17310 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17320 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
17330 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
17340 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
17350 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
17360 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
17370 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
17380 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
17390 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
173a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
173b0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
173c0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
173d0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
173e0 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
173f0 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
17400 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
17410 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
17420 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
17430 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
17440 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
17450 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
17460 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
17470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17480 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
17490 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
174a0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
174b0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
174c0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
174d0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
174e0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
174f0 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
17500 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
17510 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
17520 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
17530 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
17540 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
17550 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17560 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
17570 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17580 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17590 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
175a0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
175b0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
175c0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
175d0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
175e0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
175f0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
17600 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
17610 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
17620 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
17630 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
17640 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
17650 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
17660 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
17670 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
17680 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
17690 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
176a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
176b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
176c0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
176d0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
176e0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
176f0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
17700 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
17710 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
17720 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17730 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17740 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17760 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17770 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
17780 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
17790 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
177a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
177b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
177c0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
177d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
177e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
177f0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17800 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
17810 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
17820 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
17830 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17840 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17850 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17860 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17870 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17880 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
17890 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
178a0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
178b0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
178c0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
178d0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
178e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
178f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17900 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17910 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17920 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17930 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17940 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
17950 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
17960 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
17970 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
17980 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17990 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
179a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
179b0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
179c0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
179d0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
179e0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
179f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17a00 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17a10 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64  TS3_TOKENIZER</d
17a20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17a30 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17a40 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17a50 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67  able the two-arg
17a60 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e  ument.** version
17a70 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f   of the [fts3_to
17a80 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74  kenizer()] funct
17a90 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72  ion which is par
17aa0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53  t of the.** [FTS
17ab0 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61  3] full-text sea
17ac0 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e  rch engine exten
17ad0 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73  sion..** There s
17ae0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17af0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17b00 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17b10 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17b20 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17b30 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73  0 to disable fts
17b40 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72  3_tokenizer() or
17b50 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17b60 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  enable fts3_toke
17b70 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74  nizer() or negat
17b80 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
17b90 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68   setting.** unch
17ba0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
17bb0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
17bc0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17bd0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
17be0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
17bf0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
17c00 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74  icate whether ft
17c10 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20  s3_tokenizer is 
17c20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
17c30 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
17c40 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
17c50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17c60 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
17c70 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
17c80 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
17c90 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
17ca0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17cb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
17cc0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
17cd0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
17ce0 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 20 20  KASIDE          
17cf0 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a     1001 /* void*
17d00 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
17d10 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
17d20 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
17d30 20 20 20 20 20 20 20 20 20 20 31 30 30 32 20 2f            1002 /
17d40 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
17d50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17d60 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17d70 47 47 45 52 20 20 20 20 20 20 20 20 31 30 30 33  GGER        1003
17d80 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
17d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17da0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17db0 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30  TS3_TOKENIZER 10
17dc0 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  04 /* int int* *
17dd0 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
17de0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
17df0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
17e00 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d  esult Codes.** M
17e10 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
17e20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17e30 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
17e40 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
17e50 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
17e60 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
17e70 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
17e80 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
17e90 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
17ea0 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
17eb0 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
17ec0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
17ed0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
17ee0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69  patibility..*/.i
17ef0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
17f00 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
17f10 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
17f20 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
17f30 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
17f40 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54  ert Rowid.** MET
17f50 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
17f60 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
17f70 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61  n most SQLite ta
17f80 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72  bles (except for
17f90 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
17fa0 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20   tables).** has 
17fb0 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
17fc0 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
17fd0 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
17fe0 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
17ff0 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
18000 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
18010 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
18020 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
18030 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
18040 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
18050 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
18060 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
18070 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
18080 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
18090 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
180a0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
180b0 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
180c0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
180d0 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
180e0 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
180f0 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
18100 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
18110 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
18120 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69  nsert_rowid(D) i
18130 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
18140 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
18150 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63  the .** most rec
18160 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
18170 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
18180 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
18190 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
181a0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
181b0 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49  nection D..** ^I
181c0 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
181d0 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
181e0 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72  es are not recor
181f0 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  ded..** ^If no s
18200 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
18210 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
18220 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76  ables.** have ev
18230 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
18240 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18250 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68  ection D, .** th
18260 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
18270 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
18280 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
18290 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
182a0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
182b0 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
182c0 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
182d0 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
182e0 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
182f0 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
18300 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
18310 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
18320 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
18330 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
18340 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
18350 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
18360 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
18370 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
18380 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
18390 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
183a0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
183b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
183c0 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
183d0 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
183e0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
183f0 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
18400 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
18410 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
18420 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
18430 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
18440 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
18450 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
18460 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
18470 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
18480 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
18490 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
184a0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
184b0 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
184c0 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
184d0 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
184e0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
184f0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
18500 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
18510 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
18520 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
18530 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
18540 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
18550 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
18560 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
18570 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
18580 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
18590 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
185a0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
185b0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
185c0 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
185d0 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
185e0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
185f0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
18600 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
18610 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
18620 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
18630 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
18640 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
18650 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
18660 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
18670 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
18680 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
18690 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
186a0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
186b0 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
186c0 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
186d0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
186e0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
186f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
18700 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
18710 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
18720 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
18730 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
18740 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
18750 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
18760 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
18770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18780 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
18790 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
187a0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
187b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
187c0 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
187d0 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
187e0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
187f0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
18800 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
18810 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
18820 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
18830 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18840 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
18850 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
18860 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
18870 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
18880 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
18890 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
188a0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
188b0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
188c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
188d0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
188e0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
188f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
18900 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
18910 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
18920 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
18930 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
18940 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
18950 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
18960 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
18970 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
18980 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
18990 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74  ement on the dat
189a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
189b0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
189c0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
189d0 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20  ..** ^Executing 
189e0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
189f0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  f SQL statement 
18a00 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20  does not modify 
18a10 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
18a20 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
18a30 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  nction..**.** ^O
18a40 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
18a50 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65   directly by the
18a60 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
18a70 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
18a80 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ent are.** consi
18a90 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72  dered - auxiliar
18aa0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
18ab0 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47   by [CREATE TRIG
18ac0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c  GER | triggers],
18ad0 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65   .** [foreign ke
18ae0 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52  y actions] or [R
18af0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
18b00 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
18b10 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
18b20 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f  * .** Changes to
18b30 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
18b40 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
18b50 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20  .** [INSTEAD OF 
18b60 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41  trigger | INSTEA
18b70 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61  D OF triggers] a
18b80 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
18b90 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72  ^The value .** r
18ba0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
18bb0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d  e3_changes() imm
18bc0 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61  ediately after a
18bd0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
18be0 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73   or .** DELETE s
18bf0 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20  tatement run on 
18c00 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73  a view is always
18c10 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e   zero. Only chan
18c20 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c  ges made to real
18c30 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20   .** tables are 
18c40 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  counted..**.** T
18c50 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63  hings are more c
18c60 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68  omplicated if th
18c70 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
18c80 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  s() function is.
18c90 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c  ** executed whil
18ca0 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  e a trigger prog
18cb0 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  ram is running. 
18cc0 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20  This may happen 
18cd0 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61  if the.** progra
18ce0 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e  m uses the [chan
18cf0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18d00 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20  on], or if some 
18d10 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  other callback.*
18d20 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b  * function invok
18d30 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  es sqlite3_chang
18d40 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45  es() directly. E
18d50 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a  ssentially:.** .
18d60 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
18d70 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72  > ^(Before enter
18d80 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72  ing a trigger pr
18d90 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20  ogram the value 
18da0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
18db0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68        sqlite3_ch
18dc0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
18dd0 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72   is saved. After
18de0 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
18df0 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  gram .**        
18e00 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68  has finished, th
18e10 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65  e original value
18e20 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a   is restored.)^.
18e30 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28  ** .**   <li> ^(
18e40 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  Within a trigger
18e50 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e   program each IN
18e60 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64  SERT, UPDATE and
18e70 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20   DELETE .**     
18e80 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74     statement set
18e90 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  s the value retu
18ea0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
18eb0 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
18ec0 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65       upon comple
18ed0 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20  tion as normal. 
18ee0 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20  Of course, this 
18ef0 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69  value will not i
18f00 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20  nclude .**      
18f10 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65    any changes pe
18f20 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74  rformed by sub-t
18f30 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20  riggers, as the 
18f40 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18f50 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c  ) .**        val
18f60 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64  ue will be saved
18f70 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66   and restored af
18f80 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69  ter each sub-tri
18f90 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a  gger has run.)^.
18fa0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
18fb0 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74  ^This means that
18fc0 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28   if the changes(
18fd0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28  ) SQL function (
18fe0 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75  or similar) is u
18ff0 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69  sed.** by the fi
19000 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  rst INSERT, UPDA
19010 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
19020 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
19030 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20  trigger, it .** 
19040 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
19050 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68  e as set when th
19060 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d  e calling statem
19070 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74  ent began execut
19080 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  ing..** ^If it i
19090 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65  s used by the se
190a0 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65  cond or subseque
190b0 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e  nt such statemen
190c0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
190d0 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20  er .** program, 
190e0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
190f0 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20  ed reflects the 
19100 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d  number of rows m
19110 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  odified by the .
19120 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45  ** previous INSE
19130 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19140 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
19150 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74  ithin the same t
19160 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  rigger..**.** Se
19170 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
19180 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
19190 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
191a0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
191b0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
191c0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
191d0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
191e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
191f0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
19200 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
19210 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
19220 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
19230 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
19240 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
19250 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
19260 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
19270 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
19280 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
19290 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
192a0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
192b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
192c0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
192d0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
192e0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
192f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
19300 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
19310 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
19320 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
19330 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
19340 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
19350 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
19360 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
19370 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
19380 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
19390 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
193a0 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
193b0 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
193c0 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
193d0 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
193e0 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
193f0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
19400 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
19410 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
19420 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
19430 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19440 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
19450 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
19460 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
19470 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
19480 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
19490 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
194a0 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
194b0 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
194c0 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
194d0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
194e0 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
194f0 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
19500 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
19510 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
19520 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
19530 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
19540 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
19550 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
19560 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
19570 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
19580 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
19590 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
195a0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
195b0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
195c0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
195d0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
195e0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
195f0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
19600 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
19610 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
19620 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
19630 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
19640 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
19650 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
19660 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
19670 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
19680 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
19690 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
196a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
196b0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
196c0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
196d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
196e0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
196f0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
19700 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
19710 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
19720 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
19730 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
19740 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
19750 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
19760 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
19770 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
19780 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
19790 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
197a0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
197b0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
197c0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
197d0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
197e0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
197f0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
19800 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
19810 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
19820 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
19830 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
19840 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
19850 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
19860 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
19870 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
19880 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
19890 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
198a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
198b0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
198c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
198d0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
198e0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
198f0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
19900 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
19910 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
19920 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
19930 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
19940 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
19950 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
19960 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
19970 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
19980 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
19990 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
199a0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
199b0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
199c0 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
199d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
199e0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
199f0 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
19a00 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
19a10 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
19a20 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
19a30 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
19a40 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
19a50 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
19a60 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
19a70 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
19a80 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
19a90 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
19aa0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
19ab0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
19ac0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
19ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19ae0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
19af0 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
19b00 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
19b10 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
19b20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
19b30 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
19b40 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
19b50 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
19b60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
19b70 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
19b80 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
19b90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19ba0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
19bb0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
19bc0 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
19bd0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
19be0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
19bf0 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
19c00 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
19c10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
19c20 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
19c30 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
19c40 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
19c50 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
19c60 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
19c70 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
19c80 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
19c90 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
19ca0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19cb0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
19cc0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
19cd0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
19ce0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
19cf0 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
19d00 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19d10 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
19d20 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
19d30 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
19d40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
19d50 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
19d60 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19d70 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
19d80 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
19d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19da0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
19db0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19dc0 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
19dd0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
19de0 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
19df0 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
19e00 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19e10 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19e20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
19e30 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
19e40 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
19e50 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
19e60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
19e70 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
19e80 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
19e90 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
19ea0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
19eb0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
19ec0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
19ed0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
19ee0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
19ef0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
19f00 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
19f10 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
19f20 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
19f30 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
19f40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19f50 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
19f60 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
19f70 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
19f80 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
19f90 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
19fa0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
19fb0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
19fc0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
19fd0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
19fe0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
19ff0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
1a000 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
1a010 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
1a020 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
1a030 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
1a040 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
1a050 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
1a060 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
1a070 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
1a080 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
1a090 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
1a0a0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
1a0b0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
1a0c0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
1a0d0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
1a0e0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
1a0f0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
1a100 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
1a110 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
1a120 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
1a130 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
1a140 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
1a150 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1a160 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1a170 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
1a180 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
1a190 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
1a1a0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
1a1b0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
1a1c0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
1a1d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1a1e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1a1f0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
1a200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1a210 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
1a220 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
1a230 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
1a240 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
1a250 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
1a260 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
1a270 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
1a280 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
1a290 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
1a2a0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
1a2b0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
1a2c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1a2d0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1a2e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1a2f0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1a300 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
1a310 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
1a320 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
1a330 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1a340 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
1a350 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
1a360 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
1a370 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1a380 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1a390 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1a3a0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1a3b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1a3c0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1a3d0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1a3e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1a3f0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1a400 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1a410 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1a420 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1a430 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1a440 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1a450 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1a460 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
1a470 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1a480 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
1a490 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1a4a0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
1a4b0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
1a4c0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
1a4d0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
1a4e0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
1a4f0 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59  SY Errors.** KEY
1a500 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e  WORDS: {busy-han
1a510 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b  dler callback} {
1a520 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a  busy handler}.**
1a530 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a550 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a560 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
1a570 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1a580 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
1a590 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
1a5a0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
1a5b0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
1a5c0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1a5d0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
1a5e0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
1a5f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1a600 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a610 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
1a620 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
1a630 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
1a640 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
1a650 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a660 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
1a670 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1a680 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
1a690 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1a6a0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
1a6b0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1a6c0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
1a6d0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1a6e0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1a6f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1a700 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1a710 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
1a720 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
1a730 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
1a740 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
1a750 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1a760 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
1a770 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1a780 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1a790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1a7a0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1a7b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1a7c0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1a7d0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
1a7e0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
1a7f0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1a800 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1a810 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
1a820 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1a830 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
1a840 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1a850 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1a860 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
1a870 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
1a880 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
1a890 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
1a8a0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
1a8b0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
1a8c0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
1a8d0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
1a8e0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
1a8f0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
1a900 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
1a910 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
1a920 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
1a930 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
1a940 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
1a950 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1a960 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1a970 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1a980 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1a990 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1a9a0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1a9b0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
1a9c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
1a9d0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
1a9e0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
1a9f0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
1aa00 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
1aa10 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
1aa20 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
1aa30 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
1aa40 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
1aa50 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
1aa60 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
1aa70 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
1aa80 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
1aa90 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
1aaa0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
1aab0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
1aac0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
1aad0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1aae0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
1aaf0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1ab00 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1ab10 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1ab20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1ab30 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1ab40 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1ab50 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1ab60 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1ab70 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1ab80 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1ab90 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1aba0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1abb0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1abc0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1abd0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1abe0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1abf0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1ac00 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1ac10 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1ac20 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1ac30 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1ac40 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1ac50 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1ac60 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1ac70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1ac80 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1ac90 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1aca0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1acb0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1acc0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1acd0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1ace0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1acf0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1ad00 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1ad10 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1ad20 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1ad30 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1ad40 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1ad50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1ad60 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1ad70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1ad80 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1ad90 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1ada0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1adb0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1adc0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1add0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1ade0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1adf0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1ae00 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1ae10 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1ae20 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1ae30 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1ae40 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1ae50 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1ae60 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
1ae70 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
1ae80 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
1ae90 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
1aea0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
1aeb0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
1aec0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
1aed0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1aee0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1aef0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1af00 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1af10 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1af20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1af30 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1af40 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1af50 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
1af60 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
1af70 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1af80 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
1af90 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1afa0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1afb0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1afc0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1afd0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1afe0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1aff0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b000 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1b010 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1b020 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1b030 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
1b040 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1b050 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1b060 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
1b070 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
1b080 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1b090 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1b0a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b0b0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1b0c0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1b0d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1b0e0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1b0f0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1b100 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1b110 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1b120 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1b130 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1b140 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1b150 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1b160 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1b170 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1b180 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1b190 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1b1a0 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1b1b0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1b1c0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1b1d0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1b1e0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1b1f0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1b200 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1b210 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1b220 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1b230 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1b240 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1b250 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1b260 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1b270 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1b280 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1b290 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1b2a0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1b2b0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1b2c0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1b2d0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1b2e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1b2f0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1b300 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1b310 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1b320 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1b330 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1b340 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1b350 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1b360 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1b370 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1b380 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1b390 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1b3a0 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1b3b0 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74  _timeout].*/.int
1b3c0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1b3d0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1b3e0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1b3f0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1b400 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1b410 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1b420 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1b430 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1b440 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1b450 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1b460 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1b470 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1b480 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1b490 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1b4a0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1b4b0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1b4c0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1b4d0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1b4e0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1b4f0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1b500 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1b510 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1b520 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1b530 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1b540 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1b550 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1b560 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1b570 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1b580 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1b590 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1b5a0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1b5b0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1b5c0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1b5d0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1b5e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1b5f0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1b600 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1b610 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1b620 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1b630 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1b640 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1b650 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1b660 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1b670 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1b680 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1b690 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1b6a0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1b6b0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1b6c0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1b6d0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1b6e0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1b6f0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1b700 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1b710 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1b720 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1b730 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1b740 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1b750 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1b760 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1b770 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1b780 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1b790 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1b7a0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1b7b0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1b7c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1b7d0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1b7e0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1b7f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1b800 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1b810 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1b820 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1b830 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1b840 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1b850 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1b860 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1b870 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1b880 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1b890 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1b8a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1b8b0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1b8c0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1b8d0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1b8e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1b8f0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1b900 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1b910 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1b920 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1b930 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1b940 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b950 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1b960 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1b970 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1b980 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b990 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1b9a0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1b9b0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1b9c0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1b9d0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1b9e0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1b9f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ba00 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1ba10 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1ba20 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1ba30 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1ba40 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1ba50 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1ba60 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1ba70 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1ba80 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1ba90 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1baa0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1bab0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1bac0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1bad0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1bae0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1baf0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1bb00 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1bb10 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1bb20 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1bb30 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1bb40 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1bb50 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1bb60 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1bb70 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1bb80 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1bb90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1bba0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1bbb0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1bbc0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1bbd0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1bbe0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1bbf0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1bc00 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1bc10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1bc20 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1bc30 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1bc40 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1bc50 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1bc60 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1bc70 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1bc80 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1bc90 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1bca0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1bcb0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1bcc0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1bcd0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1bce0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1bcf0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1bd00 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1bd10 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1bd20 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1bd30 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1bd40 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1bd50 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1bd60 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1bd70 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1bd80 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1bd90 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1bda0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1bdb0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1bdc0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1bdd0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1bde0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1bdf0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1be00 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1be10 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1be20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1be30 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1be40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1be50 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1be60 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1be70 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1be80 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1be90 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1bea0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1beb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1bec0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1bed0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1bee0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1bef0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1bf00 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1bf10 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1bf20 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1bf30 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1bf40 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1bf50 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1bf60 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1bf70 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1bf80 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1bf90 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1bfa0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1bfb0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1bfc0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1bfd0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1bfe0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1bff0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1c000 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1c010 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1c020 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1c030 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1c040 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1c050 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1c060 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1c070 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1c080 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1c090 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1c0a0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1c0b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1c0c0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1c0d0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1c0e0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1c0f0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1c100 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1c110 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1c120 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1c130 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1c140 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1c150 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1c160 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1c170 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1c180 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1c190 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1c1a0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1c1b0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1c1c0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1c1d0 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1c1e0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1c1f0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1c200 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c210 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1c220 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1c230 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1c240 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1c250 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1c260 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1c270 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1c280 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1c290 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1c2a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c2b0 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1c2c0 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b   of the common K
1c2d0 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  &R formatting op
1c2e0 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73  tions,.** plus s
1c2f0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1c300 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1c310 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65  ats, detailed be
1c320 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  low..** Note tha
1c330 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f  t some of the mo
1c340 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61  re obscure forma
1c350 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72  tting options fr
1c360 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c  om recent.** C-l
1c370 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73  ibrary standards
1c380 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f   are omitted fro
1c390 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74  m this implement
1c3a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
1c3b0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1c3c0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1c3d0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1c3e0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1c3f0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1c400 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1c410 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1c420 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1c430 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1c440 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1c450 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1c460 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1c470 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c480 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1c490 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1c4a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1c4b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c4c0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1c4d0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1c4e0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1c4f0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1c500 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1c510 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1c520 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1c530 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1c540 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1c550 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1c560 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1c570 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1c580 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1c590 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1c5a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c5b0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1c5c0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1c5d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c5e0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1c5f0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1c600 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1c610 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1c620 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1c630 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1c640 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1c650 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1c660 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1c670 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1c680 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1c690 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1c6a0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1c6b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1c6c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1c6d0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1c6e0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1c6f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1c700 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1c710 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1c720 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1c730 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1c740 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1c750 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1c760 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1c770 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1c780 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1c790 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1c7a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1c7b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c7c0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1c7d0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1c7e0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1c7f0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1c800 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1c810 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1c820 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1c830 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1c840 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1c850 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1c860 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1c870 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1c880 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1c890 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1c8a0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1c8b0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1c8c0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1c8d0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1c8e0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1c8f0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1c900 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1c910 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1c920 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1c930 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1c940 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1c950 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1c960 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1c970 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1c980 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1c990 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1c9a0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1c9b0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1c9c0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1c9d0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1c9e0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1c9f0 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1ca00 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1ca10 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1ca20 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1ca30 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1ca40 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1ca50 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64  , "%Q", "%w" and
1ca60 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1ca70 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1ca80 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1ca90 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1caa0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1cab0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1cac0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1cad0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1cae0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1caf0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1cb00 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1cb10 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1cb20 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1cb30 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1cb40 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1cb50 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1cb60 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1cb70 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1cb80 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1cb90 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1cba0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1cbb0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1cbc0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1cbd0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1cbe0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1cbf0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1cc00 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1cc10 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1cc20 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1cc30 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1cc40 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1cc50 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1cc60 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1cc70 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1cc80 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1cc90 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1cca0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1ccb0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1ccc0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1ccd0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1cce0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1ccf0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1cd00 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1cd10 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1cd20 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1cd30 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1cd40 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1cd50 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1cd60 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1cd70 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1cd80 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1cd90 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1cda0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1cdb0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1cdc0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1cdd0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1cde0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1cdf0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1ce00 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1ce10 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ce20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1ce30 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1ce40 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1ce50 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1ce60 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1ce70 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1ce80 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1ce90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1cea0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1ceb0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1cec0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1ced0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1cee0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1cef0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1cf00 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1cf10 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1cf20 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1cf30 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1cf40 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1cf50 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1cf60 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1cf70 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1cf80 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1cf90 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1cfa0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1cfb0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1cfc0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1cfd0 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1cfe0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1cff0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1d000 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1d010 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1d020 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1d030 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1d040 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1d050 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1d060 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1d070 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1d080 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1d090 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1d0a0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1d0b0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1d0c0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1d0d0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1d0e0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1d0f0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1d100 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1d110 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1d120 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1d130 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1d140 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d150 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1d160 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1d170 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1d180 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1d190 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1d1a0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1d1b0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1d1c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1d1d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1d1e0 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1d1f0 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22  option is like "
1d200 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20  %q" except that 
1d210 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a  it expects to.**
1d220 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69   be contained wi
1d230 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  thin double-quot
1d240 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
1d250 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64  ngle quotes, and
1d260 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74   it.** escapes t
1d270 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20  he double-quote 
1d280 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61  character instea
1d290 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d  d of the single-
1d2a0 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74  quote.** charact
1d2b0 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20  er.)^  The "%w" 
1d2c0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1d2d0 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  n is intended fo
1d2e0 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69  r safely inserti
1d2f0 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20  ng.** table and 
1d300 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74  column names int
1d310 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20  o a constructed 
1d320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1d330 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1d340 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1d350 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1d360 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1d370 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1d380 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1d390 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1d3a0 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1d3b0 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1d3c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1d3d0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1d3e0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1d3f0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1d400 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1d410 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1d420 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1d430 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1d440 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1d450 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1d460 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1d470 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1d480 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1d490 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1d4a0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1d4b0 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1d4c0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1d4d0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1d4e0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1d4f0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1d500 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1d510 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1d520 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1d530 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1d540 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1d550 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1d560 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1d570 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1d580 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1d590 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1d5a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1d5b0 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1d5c0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1d5d0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1d5e0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1d5f0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1d600 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d610 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1d620 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1d630 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1d640 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1d650 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1d660 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1d670 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1d680 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d690 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1d6a0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1d6b0 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1d6c0 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1d6d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1d6e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1d6f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1d700 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1d710 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1d720 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d730 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1d740 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1d750 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d760 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1d770 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1d780 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1d790 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1d7a0 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1d7b0 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1d7c0 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1d7d0 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1d7e0 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1d7f0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1d800 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1d810 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1d820 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1d830 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1d840 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1d850 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1d860 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1d870 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1d880 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1d890 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1d8a0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1d8b0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1d8c0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1d8d0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1d8e0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1d8f0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1d900 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1d910 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1d920 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1d930 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1d940 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1d950 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1d960 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1d970 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1d980 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1d990 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1d9a0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1d9b0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1d9c0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1d9d0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1d9e0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1d9f0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1da00 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1da10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1da20 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1da30 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1da40 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1da50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1da60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1da70 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1da80 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1da90 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1daa0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1dab0 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1dac0 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1dad0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1dae0 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1daf0 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1db00 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1db10 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1db20 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1db30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1db40 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1db50 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1db60 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1db70 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1db80 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1db90 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1dba0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1dbb0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1dbc0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1dbd0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1dbe0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1dbf0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1dc00 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1dc10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1dc20 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1dc30 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1dc40 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1dc50 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1dc60 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1dc70 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1dc80 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1dc90 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1dca0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1dcb0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1dcc0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1dcd0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1dce0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1dcf0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1dd00 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1dd10 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1dd20 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1dd30 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1dd40 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1dd50 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1dd60 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1dd70 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1dd80 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1dd90 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1dda0 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1ddb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1ddc0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1ddd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1dde0 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1ddf0 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1de00 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1de10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1de20 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1de30 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1de40 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1de50 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1de60 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1de70 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1de80 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1de90 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1dea0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1deb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1dec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1ded0 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1dee0 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1def0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1df00 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1df10 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1df20 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1df30 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1df40 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1df50 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1df60 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1df70 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1df80 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1df90 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1dfa0 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1dfb0 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1dfc0 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1dfd0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1dfe0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1dff0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1e000 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1e010 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1e020 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1e030 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1e040 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1e050 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1e060 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1e070 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1e080 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1e090 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1e0a0 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1e0b0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1e0c0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1e0d0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1e0e0 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1e0f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1e100 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1e110 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e120 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1e130 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1e140 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1e150 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e160 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1e170 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1e180 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1e190 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1e1a0 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1e1b0 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1e1c0 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1e1d0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1e1e0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1e1f0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1e200 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1e210 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1e220 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1e230 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1e240 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1e250 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1e260 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1e270 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1e280 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1e290 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1e2a0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1e2b0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1e2c0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1e2d0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1e2e0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1e2f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1e300 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1e310 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1e320 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1e330 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1e340 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1e350 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1e360 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1e370 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1e380 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1e390 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1e3a0 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1e3b0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1e3c0 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1e3d0 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1e3e0 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1e3f0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1e400 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1e410 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1e420 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1e430 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1e440 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1e450 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1e460 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1e470 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1e480 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1e490 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1e4a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1e4b0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1e4c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1e4d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1e4e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1e4f0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1e500 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1e510 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1e520 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1e530 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1e540 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1e550 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1e560 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1e570 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1e580 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1e590 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1e5a0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1e5b0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1e5c0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1e5d0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1e5e0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1e5f0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1e600 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1e610 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1e620 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1e630 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1e640 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
1e650 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1e660 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
1e670 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
1e680 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1e690 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
1e6a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1e6b0 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
1e6c0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
1e6d0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1e6e0 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
1e6f0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
1e700 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1e710 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1e720 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1e730 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1e740 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1e750 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1e760 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1e770 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1e780 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1e790 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1e7a0 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1e7b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e7c0 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1e7d0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1e7e0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1e7f0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1e800 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1e810 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e820 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1e830 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1e840 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1e850 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1e860 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1e870 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1e880 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1e890 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e8a0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1e8b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1e8c0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1e8d0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1e8e0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1e8f0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1e900 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1e910 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1e920 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1e930 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1e940 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1e950 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1e960 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1e970 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1e980 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1e990 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1e9a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1e9b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e9c0 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1e9d0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1e9e0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1e9f0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1ea00 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1ea10 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1ea20 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1ea30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1ea40 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1ea50 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1ea60 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1ea70 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1ea80 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1ea90 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1eaa0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1eab0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1eac0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1ead0 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1eae0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1eaf0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1eb00 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1eb10 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1eb20 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1eb30 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1eb40 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1eb50 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1eb60 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1eb70 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1eb80 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1eb90 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1eba0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ebb0 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1ebc0 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1ebd0 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1ebe0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1ebf0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1ec00 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1ec10 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1ec20 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1ec30 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1ec40 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1ec50 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1ec60 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1ec70 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1ec80 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1ec90 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1eca0 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1ecb0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1ecc0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1ecd0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1ece0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1ecf0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1ed00 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1ed10 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1ed20 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1ed30 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1ed40 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1ed50 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1ed60 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1ed70 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1ed80 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1ed90 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
1eda0 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
1edb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1edc0 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
1edd0 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
1ede0 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
1edf0 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
1ee00 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
1ee10 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
1ee20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
1ee30 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
1ee40 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
1ee50 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1ee60 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1ee70 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
1ee80 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1ee90 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
1eea0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1eeb0 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
1eec0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
1eed0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
1eee0 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
1eef0 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
1ef00 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
1ef10 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1ef20 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1ef30 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1ef40 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1ef50 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1ef60 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1ef70 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1ef80 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1ef90 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1efa0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1efb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1efc0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1efd0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1efe0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1eff0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1f000 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1f010 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1f020 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1f030 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1f040 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f050 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1f060 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1f070 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1f080 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f090 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1f0a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1f0b0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1f0c0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1f0d0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1f0e0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1f0f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f100 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f110 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1f120 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f130 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1f140 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1f150 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1f160 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1f170 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1f180 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1f190 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1f1a0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1f1b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f1c0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1f1d0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1f1e0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1f1f0 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1f200 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f210 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1f220 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1f230 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1f240 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1f250 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1f260 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1f270 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1f280 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1f290 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1f2a0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1f2b0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1f2c0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1f2d0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1f2e0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1f2f0 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1f300 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1f310 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f320 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1f330 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1f340 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1f350 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1f360 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1f370 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1f380 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f390 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1f3a0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1f3b0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1f3c0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1f3d0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1f3e0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1f3f0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1f400 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1f410 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1f420 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1f430 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1f440 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1f450 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1f460 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1f470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1f480 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1f490 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1f4a0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1f4b0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1f4c0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1f4d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1f4e0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1f4f0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1f500 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1f510 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1f520 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1f530 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1f540 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1f550 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1f560 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1f570 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1f580 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1f590 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1f5a0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1f5b0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1f5c0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1f5d0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1f5e0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1f5f0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1f600 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1f610 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1f620 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1f630 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1f640 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1f650 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1f660 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1f670 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1f680 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1f690 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1f6a0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1f6b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1f6c0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1f6d0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1f6e0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1f6f0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1f700 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1f710 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1f720 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1f730 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1f740 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1f750 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1f760 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1f770 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1f780 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1f790 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1f7a0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1f7b0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1f7c0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1f7d0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1f7e0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1f7f0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1f800 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1f810 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1f820 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1f830 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1f840 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1f850 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1f860 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1f870 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1f880 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1f890 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1f8a0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1f8b0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1f8c0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1f8d0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1f8e0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1f8f0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1f900 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1f910 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1f920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1f930 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1f940 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1f950 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1f960 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1f970 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1f980 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1f990 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1f9a0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1f9b0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1f9c0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1f9d0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1f9e0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1f9f0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1fa00 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1fa10 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1fa20 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1fa30 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1fa40 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1fa50 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1fa60 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1fa70 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1fa80 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1fa90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1faa0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1fab0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1fac0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1fad0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1fae0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1faf0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1fb00 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1fb10 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1fb20 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1fb30 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1fb40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1fb50 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1fb60 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1fb70 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1fb80 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1fb90 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1fba0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1fbb0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1fbc0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1fbd0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1fbe0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1fbf0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1fc00 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1fc10 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1fc20 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1fc30 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1fc40 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1fc50 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1fc60 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1fc70 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1fc80 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1fc90 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1fca0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1fcb0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1fcc0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1fcd0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1fce0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1fcf0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1fd00 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1fd10 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1fd20 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1fd30 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1fd40 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1fd50 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1fd60 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1fd70 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1fd80 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1fd90 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1fda0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1fdb0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1fdc0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1fdd0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1fde0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1fdf0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1fe00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fe10 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1fe20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fe30 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1fe40 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1fe50 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1fe60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1fe70 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1fe80 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1fe90 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1fea0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1feb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fec0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1fed0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1fee0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1fef0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1ff00 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1ff10 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1ff20 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1ff30 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1ff40 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1ff50 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1ff60 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1ff70 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1ff80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ff90 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1ffa0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1ffb0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1ffc0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1ffd0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ffe0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1fff0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
20000 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20010 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
20020 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
20030 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
20040 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
20050 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
20060 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
20070 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
20080 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
20090 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
200a0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
200b0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
200c0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
200d0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
200e0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
200f0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
20100 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
20110 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20120 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
20130 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
20140 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
20150 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
20160 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
20170 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
20180 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
20190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
201a0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
201b0 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
201c0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
201d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
201e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
201f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
20200 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
20210 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
20220 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
20230 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
20240 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
20250 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
20260 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
20270 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
20280 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
20290 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
202a0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
202b0 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
202c0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
202d0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
202e0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
202f0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
20300 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
20310 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
20320 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
20330 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
20340 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
20350 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
20360 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
20370 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
20380 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
20390 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
203a0 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
203b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
203c0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
203d0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
203e0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
203f0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
20400 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
20410 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
20420 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
20430 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
20440 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
20450 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
20460 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
20470 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
20480 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
20490 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
204a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
204b0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
204c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
204d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
204e0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
204f0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
20500 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
20510 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
20520 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
20530 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
20540 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
20550 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
20560 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
20570 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
20580 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
20590 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
205a0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
205b0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
205c0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
205d0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
205e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
205f0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
20600 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
20610 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
20620 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
20630 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
20640 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
20650 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
20660 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
20670 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
20680 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
20690 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
206a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
206b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
206c0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
206d0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
206e0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
206f0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
20700 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
20710 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
20720 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
20730 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
20740 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
20750 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
20760 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
20770 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
20780 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
20790 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
207a0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
207b0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
207c0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
207d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
207e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
207f0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
20800 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
20810 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
20820 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
20830 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
20840 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20850 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20860 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20870 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
20880 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
20890 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
208a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
208b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
208c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
208d0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
208e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
208f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20900 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20910 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
20920 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
20930 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20940 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20960 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
20970 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
20980 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
20990 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
209a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
209b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
209c0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
209d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
209e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
209f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20a00 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
20a10 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
20a20 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
20a30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
20a40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20a50 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
20a60 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
20a70 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
20a80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20a90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20aa0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
20ab0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
20ac0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
20ad0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20ae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20af0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
20b00 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
20b10 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
20b20 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20b30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20b40 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
20b50 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
20b60 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
20b70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20b90 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
20ba0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
20bb0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
20bc0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
20bd0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20be0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
20bf0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
20c00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20c10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20c20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
20c30 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
20c40 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
20c50 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
20c60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20c70 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
20c80 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
20c90 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
20ca0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20cb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20cc0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
20cd0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
20ce0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
20cf0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
20d00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20d10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
20d20 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
20d30 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
20d40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20d50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20d60 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
20d70 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
20d80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20d90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20da0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20db0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
20dc0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
20dd0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
20de0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
20df0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
20e00 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
20e10 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
20e20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20e30 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
20e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20e50 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
20e60 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
20e70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20e80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20ea0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
20eb0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
20ec0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
20ed0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20ee0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20ef0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
20f00 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
20f10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
20f20 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
20f30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20f40 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
20f50 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
20f60 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
20f70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20f80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20f90 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
20fa0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
20fb0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
20fc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
20fe0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
20ff0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
21000 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
21010 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
21030 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
21040 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
21050 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21060 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21070 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
21080 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
21090 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
210a0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
210b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
210c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
210d0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
210e0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
210f0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
21100 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
21110 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
21120 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
21130 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
21140 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
21150 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
21160 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
21170 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
21180 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
21190 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
211a0 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
211b0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
211c0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
211d0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
211e0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
211f0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
21200 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
21210 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
21220 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
21230 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
21240 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
21250 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
21260 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
21270 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21280 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
21290 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
212a0 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
212b0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
212c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
212d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
212e0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
212f0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
21300 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
21310 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
21320 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
21330 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
21340 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
21350 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
21360 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
21370 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
21380 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
21390 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
213a0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
213b0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
213c0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
213d0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
213e0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
213f0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
21400 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
21410 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
21420 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
21430 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
21440 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
21450 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
21460 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
21470 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
21480 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
21490 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
214a0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
214b0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
214c0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
214d0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
214e0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
214f0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
21500 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
21510 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
21520 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
21530 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
21540 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
21550 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
21560 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
21570 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
21580 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
21590 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
215a0 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
215b0 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
215c0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
215d0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
215e0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
215f0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
21600 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
21610 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
21620 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
21630 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
21640 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
21650 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
21660 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
21670 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
21680 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
21690 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
216a0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
216b0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
216c0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
216d0 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
216e0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
216f0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
21700 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
21710 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
21720 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
21730 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
21740 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
21750 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
21760 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
21770 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
21780 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
21790 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
217a0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
217b0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
217c0 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
217d0 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
217e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
217f0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
21800 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
21810 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
21820 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
21830 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
21840 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
21850 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  te..*/.void *sql
21860 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
21870 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
21880 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
21890 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
218a0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
218b0 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
218c0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
218d0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
218e0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
218f0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
21900 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
21910 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21920 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
21930 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
21940 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
21950 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
21960 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
21970 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
21980 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
21990 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
219a0 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
219b0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
219c0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
219d0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
219e0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
219f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
21a00 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
21a10 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
21a20 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
21a30 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
21a40 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
21a50 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
21a60 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
21a70 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
21a80 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
21a90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
21aa0 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
21ab0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
21ac0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
21ad0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
21ae0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
21af0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
21b00 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
21b10 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
21b20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
21b30 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
21b40 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
21b50 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
21b60 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
21b70 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
21b80 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
21b90 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
21ba0 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
21bb0 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
21bc0 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
21bd0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
21be0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21bf0 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
21c00 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
21c10 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
21c20 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
21c30 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
21c40 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
21c50 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
21c60 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
21c70 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
21c80 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
21c90 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
21ca0 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
21cb0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
21cc0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
21cd0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
21ce0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
21cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21d00 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
21d10 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
21d20 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
21d30 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
21d40 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
21d50 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
21d60 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
21d70 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
21d80 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
21d90 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
21da0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
21db0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
21dc0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
21dd0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
21de0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
21df0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21e00 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
21e10 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
21e20 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
21e30 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
21e40 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
21e50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21e60 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
21e70 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
21e80 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
21e90 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
21ea0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
21eb0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
21ec0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
21ed0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
21ee0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
21ef0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
21f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21f10 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
21f20 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
21f30 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55  ction.** CONSTRU
21f40 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  CTOR: sqlite3.**
21f50 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
21f60 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
21f70 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
21f80 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79   as specified by
21f90 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d   the .** filenam
21fa0 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
21fb0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
21fc0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
21fd0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
21fe0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
21ff0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
22000 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
22010 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
22020 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
22030 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
22040 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
22050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22060 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
22070 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
22080 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
22090 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
220a0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
220b0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
220c0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
220d0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
220e0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
220f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
22100 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
22110 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
22120 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
22130 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
22140 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
22150 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
22160 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
22170 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
22180 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
22190 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
221a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
221b0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
221c0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
221d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
221e0 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
221f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
22200 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
22210 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
22220 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
22230 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
22240 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
22250 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
22260 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
22270 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
22280 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
22290 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
222a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
222b0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
222c0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f  will be UTF-8 fo
222d0 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61  r databases crea
222e0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c  ted using.** sql
222f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
22300 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22310 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
22320 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74  encoding for dat
22330 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65  abases.** create
22340 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
22350 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65  open16() will be
22360 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
22370 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
22380 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
22390 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
223a0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
223b0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
223c0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
223d0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
223e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
223f0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
22400 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
22410 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
22420 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
22430 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
22440 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
22450 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22460 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
22470 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
22480 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
22490 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
224a0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
224b0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
224c0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
224d0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
224e0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
224f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
22500 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
22510 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
22520 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
22530 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
22540 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
22550 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
22560 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
22570 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
22580 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
22590 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
225a0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
225b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
225c0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
225d0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
225e0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
225f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
22600 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
22610 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
22620 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
22630 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
22640 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
22650 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
22660 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
22670 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
22680 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
22690 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
226a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
226b0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
226c0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
226d0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
226e0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
226f0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
22700 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
22710 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
22720 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
22730 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
22740 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
22750 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
22760 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
22770 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
22780 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
22790 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
227a0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
227b0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
227c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
227d0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
227e0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
227f0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
22800 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
22810 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
22820 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
22830 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
22840 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
22850 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
22860 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
22870 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
22880 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
22890 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
228a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
228b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
228c0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
228d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
228e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
228f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22900 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
22910 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
22920 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
22930 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
22940 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
22950 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
22960 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
22970 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
22980 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
22990 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
229a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
229b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
229c0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
229d0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
229e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
229f0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
22a00 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
22a10 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
22a20 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
22a30 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
22a40 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
22a50 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
22a60 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
22a70 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
22a80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
22a90 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
22aa0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
22ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22ac0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
22ad0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
22ae0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
22af0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
22b00 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
22b10 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
22b20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
22b30 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
22b40 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22b50 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
22b60 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
22b70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b80 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
22b90 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
22ba0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
22bb0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
22bc0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
22bd0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
22be0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
22bf0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
22c00 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
22c10 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
22c20 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22c30 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
22c40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22c50 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
22c60 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
22c70 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
22c80 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
22c90 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
22ca0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
22cb0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
22cc0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
22cd0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
22ce0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
22cf0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
22d00 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
22d10 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
22d20 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
22d30 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
22d40 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
22d50 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
22d60 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
22d70 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
22d80 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
22d90 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
22da0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
22db0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
22dc0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
22dd0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
22de0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
22df0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
22e00 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
22e10 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
22e20 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
22e30 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
22e40 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
22e50 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
22e60 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
22e70 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
22e80 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22e90 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
22ea0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
22eb0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
22ec0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
22ed0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
22ee0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
22ef0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
22f00 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
22f10 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
22f20 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
22f30 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
22f40 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
22f50 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
22f60 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
22f70 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
22f80 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
22f90 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
22fa0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
22fb0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
22fc0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
22fd0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
22fe0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
22ff0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
23000 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
23010 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
23020 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
23030 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
23040 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
23050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
23060 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
23070 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
23080 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
23090 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
230a0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
230b0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
230c0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
230d0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
230e0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
230f0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
23100 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
23110 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
23120 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
23130 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
23140 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
23150 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
23160 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
23170 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
23180 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
23190 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
231a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
231b0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
231c0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
231d0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
231e0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
231f0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
23200 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
23210 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
23220 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
23230 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
23240 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
23250 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
23260 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
23270 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
23280 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
23290 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
232a0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
232b0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
232c0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
232d0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
232e0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
232f0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
23300 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
23310 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
23320 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
23330 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
23340 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
23350 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
23360 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
23370 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
23380 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
23390 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
233a0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
233b0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
233c0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
233d0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
233e0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
233f0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
23400 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
23410 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
23420 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
23430 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
23440 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
23450 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
23460 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
23470 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
23480 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
23490 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
234a0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
234b0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
234c0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
234d0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
234e0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
234f0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
23500 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
23510 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
23520 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
23530 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
23540 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
23550 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
23560 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
23570 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
23580 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
23590 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
235a0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
235b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
235c0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
235d0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
235e0 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69  ath. .** ^(On wi
235f0 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
23600 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
23610 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
23620 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
23630 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
23640 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a  . "C:").)^.**.**
23650 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
23660 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
23670 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
23680 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
23690 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
236a0 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
236b0 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
236c0 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
236d0 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
236e0 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
236f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
23700 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  ..** SQLite and 
23710 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46  its built-in [VF
23720 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74  Ses] interpret t
23730 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
23740 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
23750 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
23760 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
23770 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
23780 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
23790 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
237a0 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
237b0 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
237c0 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
237d0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
237e0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
237f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
23800 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
23810 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23820 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
23830 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
23840 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
23850 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
23860 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
23870 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
23880 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
23890 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
238a0 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
238b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
238c0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
238d0 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
238e0 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
238f0 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
23900 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
23910 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
23920 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
23930 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
23940 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
23950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
23960 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
23970 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
23980 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
23990 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
239a0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
239b0 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
239c0 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
239d0 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
239e0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
239f0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
23a00 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
23a10 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
23a20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
23a30 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
23a40 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
23a50 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
23a60 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
23a70 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
23a80 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
23a90 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
23aa0 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
23ab0 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
23ac0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
23ad0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
23ae0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
23af0 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
23b00 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
23b10 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
23b20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
23b30 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
23b40 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
23b50 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
23b60 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
23b70 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
23b80 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
23b90 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
23ba0 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
23bb0 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
23bc0 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
23bd0 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
23be0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
23bf0 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
23c00 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
23c10 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
23c20 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
23c30 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
23c40 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
23c50 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
23c60 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
23c70 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
23c80 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
23c90 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
23ca0 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
23cb0 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
23cc0 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
23cd0 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
23ce0 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
23cf0 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
23d00 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
23d10 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
23d20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
23d30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23d40 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
23d50 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
23d60 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
23d70 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
23d80 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
23d90 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
23da0 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
23db0 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
23dc0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
23dd0 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
23de0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
23df0 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
23e00 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
23e10 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
23e20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
23e30 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
23e40 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
23e50 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
23e60 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
23e70 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
23e80 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
23e90 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
23ea0 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
23eb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23ec0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
23ed0 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
23ee0 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
23ef0 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
23f00 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
23f10 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
23f20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
23f30 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
23f40 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
23f50 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
23f60 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
23f70 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
23f80 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
23f90 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
23fa0 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69  w parameter indi
23fb0 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72  cates whether or
23fc0 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   not the.**     
23fd0 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77  [powersafe overw
23fe0 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64  rite] property d
23ff0 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20  oes or does not 
24000 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20  apply to the.** 
24010 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69      storage medi
24020 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64  a on which the d
24030 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73  atabase file res
24040 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ides..**.**  <li
24050 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a  > <b>nolock</b>:
24060 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72   ^The nolock par
24070 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
24080 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65  ean query parame
24090 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68  ter.**     which
240a0 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73   if set disables
240b0 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e   file locking in
240c0 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
240d0 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a  l modes.  This.*
240e0 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20  *     is useful 
240f0 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20  for accessing a 
24100 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69  database on a fi
24110 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f  lesystem that do
24120 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75  es not.**     su
24130 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20  pport locking.  
24140 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61  Caution:  Databa
24150 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69  se corruption mi
24160 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77  ght result if tw
24170 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65  o.**     or more
24180 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65   processes write
24190 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
241a0 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e  abase and any on
241b0 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20  e of those.**   
241c0 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73    processes uses
241d0 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a   nolock=1..**.**
241e0 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61    <li> <b>immuta
241f0 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d  ble</b>: ^The im
24200 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65  mutable paramete
24210 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
24220 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
24230 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63  meter that indic
24240 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61  ates that the da
24250 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73  tabase file is s
24260 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  tored on.**     
24270 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
24280 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c    ^When immutabl
24290 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65  e is set, SQLite
242a0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
242b0 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73  e.**     databas
242c0 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  e file cannot be
242d0 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62   changed, even b
242e0 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68  y a process with
242f0 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70   higher.**     p
24300 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f  rivilege, and so
24310 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
24320 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c   opened read-onl
24330 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e  y and all lockin
24340 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61  g.**     and cha
24350 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73  nge detection is
24360 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74   disabled.  Caut
24370 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65  ion: Setting the
24380 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20   immutable.**   
24390 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20    property on a 
243a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
243b0 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20  at does in fact 
243c0 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c  change can resul
243d0 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f  t.**     in inco
243e0 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75  rrect query resu
243f0 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  lts and/or [SQLI
24400 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f  TE_CORRUPT] erro
24410 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61  rs..**     See a
24420 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43  lso: [SQLITE_IOC
24430 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a  AP_IMMUTABLE]..*
24440 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c  *       .** </ul
24450 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
24460 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
24470 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
24480 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
24490 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
244a0 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
244b0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
244c0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
244d0 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
244e0 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
244f0 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
24500 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
24510 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
24520 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
24530 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
24540 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
24550 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
24560 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
24570 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
24580 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
24590 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
245a0 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
245b0 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
245c0 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
245d0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
245e0 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
245f0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
24600 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
24610 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
24620 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
24630 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
24640 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
24650 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
24660 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
24670 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
24680 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
24690 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
246a0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
246b0 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
246c0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
246d0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
246e0 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
246f0 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
24700 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
24710 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
24720 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
24730 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
24740 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
24750 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
24760 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
24770 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
24780 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
24790 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
247a0 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
247b0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
247c0 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
247d0 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
247e0 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
247f0 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
24800 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
24810 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
24820 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
24830 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
24840 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
24850 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
24860 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
24870 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
24880 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
24890 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
248a0 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
248b0 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
248c0 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
248d0 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
248e0 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
248f0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
24900 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
24910 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
24920 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
24930 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
24940 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
24950 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
24960 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
24970 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
24980 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
24990 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
249a0 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
249b0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
249c0 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
249d0 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
249e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
249f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24a00 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66  db?vfs=unix-dotf
24a10 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ile <td>.**     
24a20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
24a30 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24a40 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
24a50 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64  cial VFS "unix-d
24a60 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20  otfile".**      
24a70 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f      that uses do
24a80 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65  t-files in place
24a90 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f   of posix adviso
24aa0 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c  ry locking..** <
24ab0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
24ac0 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
24ad0 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
24ae0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
24af0 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
24b00 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
24b10 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
24b20 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
24b30 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
24b40 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
24b50 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
24b60 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
24b70 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
24b80 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
24b90 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
24ba0 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
24bb0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
24bc0 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
24bd0 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
24be0 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
24bf0 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
24c00 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
24c10 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
24c20 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
24c30 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
24c40 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
24c50 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
24c60 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
24c70 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
24c80 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
24c90 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
24ca0 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
24cb0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
24cc0 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
24cd0 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
24ce0 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
24cf0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
24d00 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
24d10 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
24d20 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
24d30 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
24d40 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
24d50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
24d60 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
24d70 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
24d80 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
24d90 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
24da0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
24db0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
24dc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24dd0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
24de0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
24df0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
24e00 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
24e10 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
24e20 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
24e30 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
24e40 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
24e50 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
24e60 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
24e70 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
24e80 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
24e90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24ea0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
24eb0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
24ec0 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
24ed0 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
24ee0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
24ef0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
24f00 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
24f10 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
24f20 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
24f30 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
24f40 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
24f50 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
24f60 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
24f70 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
24f80 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
24f90 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
24fa0 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tory].*/.int sql
24fb0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
24fc0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
24fd0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
24fe0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
24ff0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
25000 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
25010 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
25020 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
25030 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
25040 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
25050 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
25060 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
25070 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
25080 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
25090 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
250a0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
250b0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
250c0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
250d0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
250e0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
250f0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
25100 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
25110 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
25120 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
25130 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
25140 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
25150 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
25160 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
25170 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
25180 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
25190 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
251a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
251b0 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
251c0 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
251d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
251e0 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
251f0 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
25200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
25210 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
25220 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
25230 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
25240 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
25250 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
25260 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
25270 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
25280 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
25290 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
252a0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
252b0 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
252c0 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
252d0 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
252e0 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
252f0 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
25300 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
25310 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
25320 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
25330 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
25340 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
25350 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
25360 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
25370 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
25380 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
25390 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
253a0 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
253b0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
253c0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
253d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
253e0 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
253f0 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
25400 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
25410 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
25420 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
25430 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
25440 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
25450 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
25460 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
25470 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
25480 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
25490 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
254a0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
254b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
254c0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
254d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
254e0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
254f0 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
25500 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
25510 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
25520 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
25530 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
25540 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
25550 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
25560 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
25570 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
25580 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
25590 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
255a0 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
255b0 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
255c0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
255d0 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
255e0 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
255f0 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
25600 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
25610 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
25620 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
25630 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
25640 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
25650 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
25660 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
25670 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
25680 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
25690 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
256a0 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
256b0 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
256c0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
256d0 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
256e0 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
256f0 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
25700 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
25710 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
25720 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
25730 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
25740 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
25750 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
25760 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
25770 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
25780 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
25790 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
257a0 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
257b0 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
257c0 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
257d0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
257e0 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
257f0 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
25800 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
25810 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
25820 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
25830 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
25840 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
25850 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
25860 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
25870 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
25880 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
25890 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
258a0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
258b0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
258c0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
258d0 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
258e0 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
258f0 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
25900 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
25910 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
25920 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
25930 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
25940 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
25950 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
25960 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
25970 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
25980 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
25990 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
259a0 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  le..*/.const cha
259b0 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
259c0 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
259d0 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
259e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
259f0 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  am);.int sqlite3
25a00 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
25a10 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
25a20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
25a30 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
25a40 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
25a50 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
25a60 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
25a70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
25a80 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
25a90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
25aa0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
25ab0 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
25ac0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
25ad0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
25ae0 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
25af0 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
25b00 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
25b10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25b20 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
25b30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
25b40 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
25b50 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
25b60 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
25b70 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
25b80 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
25b90 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
25ba0 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
25bb0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
25bc0 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
25bd0 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
25be0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
25bf0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
25c00 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
25c10 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
25c20 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
25c30 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
25c40 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
25c50 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
25c60 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
25c70 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
25c80 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
25c90 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
25ca0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
25cb0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
25cc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25cd0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
25ce0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
25cf0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
25d00 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
25d10 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
25d20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
25d30 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
25d40 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
25d50 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
25d60 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
25d70 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
25d80 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
25d90 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
25da0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
25db0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
25dc0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
25dd0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
25de0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
25df0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
25e00 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
25e10 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
25e20 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
25e30 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
25e40 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
25e50 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
25e60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
25e70 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
25e80 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
25e90 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
25ea0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
25eb0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
25ec0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
25ed0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
25ee0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
25ef0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
25f00 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
25f10 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
25f20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
25f30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
25f40 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
25f50 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
25f60 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
25f70 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
25f80 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
25f90 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
25fa0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
25fb0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
25fc0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
25fd0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
25fe0 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
25ff0 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
26000 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
26010 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
26020 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
26030 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
26040 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
26050 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
26060 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
26070 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
26080 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
26090 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
260a0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
260b0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
260c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
260d0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
260e0 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
260f0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
26100 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
26110 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
26120 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
26130 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
26140 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
26150 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
26160 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
26170 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
26180 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
26190 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
261a0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
261b0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
261c0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
261d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
261e0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
261f0 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
26200 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
26210 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
26220 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
26230 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
26240 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
26250 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
26260 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
26270 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
26280 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
26290 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
262a0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
262b0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
262c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
262d0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
262e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
262f0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
26300 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63  lite3*);.const c
26310 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
26320 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
26330 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61   CAPI3REF: Prepa
26340 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
26350 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
26360 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
26370 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
26380 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
26390 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
263a0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
263b0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
263c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
263d0 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e  that.** has been
263e0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62   compiled into b
263f0 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69  inary form and i
26400 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76  s ready to be ev
26410 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  aluated..**.** T
26420 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c  hink of each SQL
26430 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20   statement as a 
26440 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65  separate compute
26450 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a  r program.  The.
26460 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
26470 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63  text is source c
26480 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64  ode.  A prepared
26490 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
264a0 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d  t .** is the com
264b0 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64  piled object cod
264c0 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74  e.  All SQL must
264d0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   be converted in
264e0 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64  to a.** prepared
264f0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72   statement befor
26500 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e  e it can be run.
26510 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d  .**.** The life-
26520 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61  cycle of a prepa
26530 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
26540 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65  ject usually goe
26550 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  s like this:.**.
26560 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
26570 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61  Create the prepa
26580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
26590 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
265a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
265b0 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  ]..** <li> Bind 
265c0 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d  values to [param
265d0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
265e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
265f0 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
26600 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
26610 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
26620 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
26630 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
26640 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
26650 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61   Reset the prepa
26660 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
26670 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
26680 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
26690 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
266a0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
266b0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
266c0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
266d0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
266e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
266f0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
26700 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  l>.*/.typedef st
26710 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
26720 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
26730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26740 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
26750 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
26760 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  te3.**.** ^(This
26770 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
26780 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
26790 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
267a0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
267b0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
267c0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
267d0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
267e0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
267f0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
26800 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
26810 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
26820 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
26830 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
26840 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
26850 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
26860 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
26870 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
26880 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
26890 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
268a0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
268b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
268c0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
268d0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
268e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
268f0 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
26900 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
26910 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
26920 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f  changed..** ^(Fo
26930 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74  r each limit cat
26940 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d  egory SQLITE_LIM
26950 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74  IT_<i>NAME</i> t
26960 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
26970 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
26980 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
26990 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
269a0 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65   by a C preproce
269b0 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65  ssor macro calle
269c0 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53  d.** [limits | S
269d0 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d  QLITE_MAX_<i>NAM
269e0 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20  E</i>]..** (The 
269f0 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
26a00 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
26a10 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a   to "_MAX_".))^.
26a20 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20  ** ^Attempts to 
26a30 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
26a40 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
26a50 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
26a60 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
26a70 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
26a80 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a  d upper bound..*
26a90 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73  *.** ^Regardless
26aa0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
26ab0 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73  ot the limit was
26ac0 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a   changed, the .*
26ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  * [sqlite3_limit
26ae0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
26af0 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20  turns the prior 
26b00 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
26b10 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74  it..** ^Hence, t
26b20 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65  o find the curre
26b30 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69  nt value of a li
26b40 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e  mit without chan
26b50 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70  ging it,.** simp
26b60 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69  ly invoke this i
26b70 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68  nterface with th
26b80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
26b90 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a  r set to -1..**.
26ba0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
26bb0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
26bc0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
26bd0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
26be0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
26bf0 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
26c00 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
26c10 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
26c20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
26c30 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
26c40 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
26c50 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
26c60 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
26c70 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
26c80 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
26c90 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
26ca0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
26cb0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
26cc0 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
26cd0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
26ce0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
26cf0 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
26d00 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
26d10 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
26d20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
26d30 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
26d40 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
26d50 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
26d60 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
26d70 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
26d80 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
26d90 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
26da0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
26db0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
26dc0 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
26dd0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
26de0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
26df0 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
26e00 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
26e10 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
26e20 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
26e30 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
26e40 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
26e50 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
26e60 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
26e70 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
26e80 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
26e90 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
26ea0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
26eb0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
26ec0 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
26ed0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
26ee0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
26ef0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
26f00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
26f10 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
26f20 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
26f30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26f40 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
26f50 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
26f60 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
26f70 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
26f80 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
26f90 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
26fa0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
26fb0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
26fc0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
26fd0 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
26fe0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
26ff0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
27000 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
27010 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
27020 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
27030 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
27040 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
27050 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
27060 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
27070 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
27080 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
27090 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
270a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
270b0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
270c0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
270d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
270e0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
270f0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
27100 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
27110 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
27120 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27130 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
27140 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27150 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
27160 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27170 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
27180 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
27190 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
271a0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
271b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
271c0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
271d0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
271e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
271f0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
27200 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
27210 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
27220 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
27230 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
27240 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
27250 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
27260 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
27270 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
27280 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
27290 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
272a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
272b0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
272c0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
272d0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
272e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
272f0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
27300 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
27310 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
27320 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
27330 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27340 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
27350 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27360 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
27370 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
27380 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
27390 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
273a0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
273b0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
273c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
273d0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
273e0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
273f0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
27400 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27410 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
27420 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
27430 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
27440 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
27450 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
27460 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
27470 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
27480 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
27490 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
274a0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
274b0 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
274c0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
274d0 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
274e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
274f0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
27500 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
27510 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
27520 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
27530 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
27540 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
27550 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
27560 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
27570 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
27580 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
27590 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
275a0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
275b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
275c0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
275d0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
275e0 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
275f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27600 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
27610 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
27620 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
27630 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
27640 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27650 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
27660 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
27670 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
27680 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
27690 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
276a0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
276b0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
276c0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
276d0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
276e0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
276f0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
27700 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
27710 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
27720 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
27730 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
27740 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27750 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
27760 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
27770 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
27780 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
27790 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
277a0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
277b0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
277c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
277d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
277e0 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c  ER_THREADS]] ^(<
277f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27800 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f  WORKER_THREADS</
27810 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27820 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
27830 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65   auxiliary worke
27840 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61  r threads that a
27850 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70   single.** [prep
27860 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27870 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29  may start.</dd>)
27880 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
27890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
278a0 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
278b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
278c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
278d0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
278e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
278f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27900 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
27910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
27920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27930 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
27940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27950 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
27960 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
27970 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
27980 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
27990 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
279a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
279b0 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
279c0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
279d0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
279e0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
279f0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
27a00 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
27a10 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
27a20 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
27a30 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
27a40 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
27a50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
27a60 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
27a70 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
27a80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
27a90 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
27aa0 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
27ab0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f   SQLITE_LIMIT_WO
27ac0 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20  RKER_THREADS    
27ad0 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a         11../*.**
27ae0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
27af0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
27b00 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
27b10 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
27b20 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d  t compiler}.** M
27b30 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
27b40 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
27b50 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
27b60 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
27b70 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
27b80 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
27b90 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
27ba0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
27bb0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
27bc0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
27bd0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
27be0 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
27bf0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
27c00 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
27c10 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
27c20 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
27c30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
27c40 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
27c50 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
27c60 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
27c70 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
27c80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
27c90 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
27ca0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
27cb0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
27cc0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
27cd0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
27ce0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
27cf0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
27d00 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
27d10 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
27d20 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
27d30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27d40 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
27d50 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
27d60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27d70 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
27d80 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
27d90 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
27da0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
27db0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65  e argument is ne
27dc0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71  gative, then zSq
27dd0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
27de0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
27df0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
27e00 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74  f nByte is posit
27e10 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
27e20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
27e30 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
27e40 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74   zSql.  ^If nByt
27e50 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  e is zero, then 
27e60 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  no prepared.** s
27e70 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65  tatement is gene
27e80 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  rated..** If the
27e90 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68   caller knows th
27ea0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
27eb0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
27ec0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a  rminated, then.*
27ed0 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  * there is a sma
27ee0 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ll performance a
27ef0 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73  dvantage to pass
27f00 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
27f10 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
27f20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
27f30 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
27f40 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
27f50 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
27f60 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
27f70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
27f80 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
27f90 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
27fa0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
27fb0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
27fc0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
27fd0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
27fe0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
27ff0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
28000 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
28010 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
28020 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
28030 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
28040 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
28050 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
28060 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
28070 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
28080 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
28090 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
280a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
280b0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
280c0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
280d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
280e0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
280f0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
28100 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
28110 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
28120 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
28130 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
28140 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
28150 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
28160 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
28170 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
28180 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
28190 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
281a0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
281b0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
281c0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
281d0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
281e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
281f0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
28200 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
28210 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
28220 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
28230 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
28240 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
28250 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
28260 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
28270 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
28280 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
28290 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
282a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
282b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
282c0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
282d0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
282e0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
282f0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
28300 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
28310 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
28320 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
28330 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
28340 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
28350 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
28360 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
28370 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
28380 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
28390 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
283a0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
283b0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
283c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
283d0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
283e0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
283f0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
28400 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
28410 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
28420 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
28430 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
28440 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
28450 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
28460 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
28470 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
28480 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
28490 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
284a0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
284b0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
284c0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
284d0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
284e0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
284f0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
28500 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
28510 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
28520 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
28530 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
28540 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
28550 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
28560 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
28570 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
28580 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
28590 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
285a0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
285b0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
285c0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
285d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
285e0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
285f0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
28600 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
28610 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
28620 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
28630 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
28640 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
28650 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
28660 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
28670 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
28680 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
28690 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
286a0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
286b0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
286c0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
286d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
286e0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
286f0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
28700 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
28710 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
28720 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
28730 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
28740 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
28750 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
28760 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
28770 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
28780 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
28790 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
287a0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
287b0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
287c0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
287d0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
287e0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
287f0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
28800 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
28810 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
28820 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
28830 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
28840 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
28850 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
28860 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
28870 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
28880 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
28890 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
288a0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
288b0 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
288c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
288d0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
288e0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
288f0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
28900 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
28910 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
28920 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
28930 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
28940 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
28950 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
28960 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
28970 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
28980 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
28990 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
289a0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
289b0 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
289c0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
289d0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
289e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
289f0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
28a00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
28a10 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
28a20 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
28a30 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
28a40 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
28a50 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
28a60 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
28a70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
28a80 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
28a90 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
28aa0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
28ab0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
28ac0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
28ad0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28ae0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
28af0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
28b00 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28b10 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28b20 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28b30 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
28b40 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
28b50 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
28b60 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
28b70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
28b80 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
28b90 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28ba0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
28bb0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28bc0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
28bd0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
28be0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
28bf0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
28c00 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28c10 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28c20 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28c30 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28c40 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28c50 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28c60 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28c70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
28c80 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28c90 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28ca0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28cb0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
28cc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
28cd0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
28ce0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
28cf0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
28d00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
28d10 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
28d20 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
28d30 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
28d40 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
28d50 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
28d60 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
28d70 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
28d80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
28d90 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
28da0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
28db0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
28dc0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
28dd0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
28de0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
28df0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
28e00 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
28e10 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
28e20 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
28e30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
28e40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28e50 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
28e60 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
28e70 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
28e80 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
28e90 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
28ea0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
28eb0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
28ec0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
28ed0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
28ee0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
28ef0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
28f00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
28f10 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
28f20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
28f30 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
28f40 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
28f50 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
28f60 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
28f70 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  L.** METHOD: sql
28f80 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
28f90 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
28fa0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
28fb0 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
28fc0 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
28fd0 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
28fe0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
28ff0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
29000 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
29010 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
29020 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
29030 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
29040 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
29050 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29060 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
29070 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29080 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
29090 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
290a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
290b0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
290c0 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
290d0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
290e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
290f0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
29100 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
29110 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
29120 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
29130 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
29140 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
29150 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29160 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
29170 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
29180 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
29190 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
291a0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
291b0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
291c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
291d0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
291e0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
291f0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
29200 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
29210 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
29220 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
29230 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
29240 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
29250 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
29260 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
29270 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
29280 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
29290 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
292a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
292b0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
292c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
292d0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
292e0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
292f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
29300 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
29310 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
29320 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
29330 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
29340 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
29350 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
29360 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
29370 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
29380 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
29390 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
293a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
293b0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
293c0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
293d0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
293e0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
293f0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
29400 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
29410 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
29420 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
29430 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
29440 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
29450 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
29460 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
29470 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
29480 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
29490 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
294a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
294b0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
294c0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
294d0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
294e0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
294f0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
29500 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
29510 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
29520 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
29530 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
29540 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
29550 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
29560 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
29570 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
29580 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
29590 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
295a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
295b0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
295c0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
295d0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
295e0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
295f0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
29600 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29610 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
29620 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
29630 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29640 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
29650 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
29660 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
29670 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Reset.** METHOD:
29680 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
29690 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
296a0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
296b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
296c0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
296d0 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
296e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
296f0 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
29700 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
29710 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
29720 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
29730 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20  has neither run 
29740 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72  to completion (r
29750 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
29760 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73  TE_DONE] from [s
29770 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29  qlite3_step(S)])
29780 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73   nor.** been res
29790 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
297a0 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
297b0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
297c0 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
297d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
297e0 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
297f0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
29800 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
29810 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
29820 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
29830 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
29840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
29850 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
29860 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
29870 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
29880 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
29890 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
298a0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
298b0 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
298c0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
298d0 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
298e0 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
298f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
29900 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
29910 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
29920 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
29930 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
29940 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
29950 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
29960 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
29970 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
29980 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
29990 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
299a0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
299b0 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
299c0 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
299d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
299e0 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
299f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
29a00 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
29a10 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
29a20 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
29a30 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
29a40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
29a50 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29a60 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
29a70 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
29a80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29a90 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
29aa0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
29ab0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
29ac0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
29ad0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
29ae0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
29af0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
29b00 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
29b10 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
29b20 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
29b30 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
29b40 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
29b50 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
29b60 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
29b70 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
29b80 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
29b90 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
29ba0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
29bb0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
29bc0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
29bd0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
29be0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
29bf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
29c00 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
29c10 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
29c20 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
29c30 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
29c40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29c50 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
29c60 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
29c70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
29c80 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
29c90 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
29ca0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
29cb0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
29cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54  qlite3_value.  T
29cd0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
29ce0 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65  alue_dup()] inte
29cf0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
29d00 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61  d to construct a
29d10 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74   new .** protect
29d20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29d30 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65   from an unprote
29d40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29d50 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
29d60 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
29d70 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
29d80 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
29d90 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
29da0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
29db0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
29dc0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
29dd0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29de0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29df0 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
29e00 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
29e10 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29e20 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29e30 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
29e40 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
29e50 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
29e60 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
29e70 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
29e80 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
29e90 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
29ea0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
29eb0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
29ec0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
29ed0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
29ee0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
29ef0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
29f00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
29f10 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
29f20 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
29f30 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
29f40 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
29f50 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
29f60 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
29f70 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
29f80 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
29f90 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
29fa0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
29fb0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
29fc0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
29fd0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
29fe0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
29ff0 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
2a000 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2a010 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2a020 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2a030 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2a040 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
2a050 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
2a060 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
2a070 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2a080 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
2a090 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
2a0a0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
2a0b0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2a0c0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
2a0d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2a0e0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
2a0f0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
2a100 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a110 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2a120 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2a130 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2a140 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
2a150 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
2a160 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2a170 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
2a180 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
2a190 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2a1a0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2a1b0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
2a1c0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2a1d0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2a1e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2a1f0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2a200 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2a210 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2a220 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2a230 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2a240 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
2a250 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
2a260 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
2a270 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
2a280 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2a290 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
2a2a0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
2a2b0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
2a2c0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
2a2d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
2a2e0 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
2a2f0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
2a300 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
2a310 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
2a320 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
2a330 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a340 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2a350 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
2a360 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2a370 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
2a380 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
2a390 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
2a3a0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
2a3b0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
2a3c0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
2a3d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
2a3e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2a3f0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2a400 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
2a410 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
2a420 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2a430 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
2a440 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2a450 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
2a460 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
2a470 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
2a480 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2a490 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
2a4a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
2a4b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
2a4c0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
2a4d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2a4e0 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
2a4f0 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
2a500 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
2a510 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
2a520 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
2a530 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
2a540 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
2a550 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
2a560 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20  ter binding}.** 
2a570 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2a580 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  stmt.**.** ^(In 
2a590 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2a5a0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
2a5b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a5c0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
2a5d0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
2a5e0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
2a5f0 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
2a600 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
2a610 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
2a620 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
2a630 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2a640 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
2a650 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
2a660 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
2a670 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
2a680 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2a690 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
2a6a0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
2a6b0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
2a6c0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
2a6d0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
2a6e0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
2a6f0 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
2a700 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
2a710 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
2a720 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
2a730 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2a740 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
2a750 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
2a760 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
2a770 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a780 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
2a790 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
2a7a0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2a7b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
2a7c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2a7d0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
2a7e0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
2a7f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2a800 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
2a810 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
2a820 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a830 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
2a840 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
2a850 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2a860 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2a870 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
2a880 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
2a890 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
2a8a0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2a8b0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
2a8c0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
2a8d0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
2a8e0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
2a8f0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
2a900 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
2a910 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
2a920 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
2a930 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
2a940 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
2a950 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
2a960 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
2a970 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
2a980 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
2a990 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a9a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
2a9b0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
2a9c0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
2a9d0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
2a9e0 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
2a9f0 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
2aa00 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
2aa10 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
2aa20 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
2aa30 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
2aa40 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
2aa50 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2aa60 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
2aa70 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
2aa80 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
2aa90 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
2aaa0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
2aab0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
2aac0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2aad0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2aae0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2aaf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ab00 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  t16().** or sqli
2ab10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2ab20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2ab30 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  r then the fourt
2ab40 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  h parameter.** i
2ab50 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68  s ignored and th
2ab60 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20  e end result is 
2ab70 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69  the same as sqli
2ab80 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e  te3_bind_null().
2ab90 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
2aba0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
2abb0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
2abc0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
2abd0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2abe0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2abf0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
2ac00 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
2ac10 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2ac20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
2ac30 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
2ac40 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
2ac50 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2ac60 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
2ac70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ac80 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2ac90 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2aca0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2acb0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2acc0 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
2acd0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
2ace0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2acf0 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
2ad00 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
2ad10 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
2ad20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2ad30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2ad40 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
2ad50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
2ad60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2ad70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2ad80 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
2ad90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2ada0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
2adb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2adc0 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
2add0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2ade0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2adf0 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a  _text64() then.*
2ae00 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  * that parameter
2ae10 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
2ae20 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
2ae30 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
2ae40 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
2ae50 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
2ae60 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
2ae70 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
2ae80 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
2ae90 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
2aea0 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
2aeb0 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
2aec0 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
2aed0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
2aee0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
2aef0 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
2af00 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
2af10 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
2af20 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
2af30 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
2af40 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
2af50 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
2af60 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2af70 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
2af80 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  ent to the BLOB 
2af90 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69  and string bindi
2afa0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  ng interfaces.**
2afb0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
2afc0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
2afd0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
2afe0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
2aff0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
2b000 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
2b010 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2b020 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
2b030 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2b040 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
2b050 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
2b060 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a  bind API fails..
2b070 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2b080 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
2b090 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
2b0a0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
2b0b0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
2b0c0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
2b0d0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
2b0e0 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
2b0f0 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
2b100 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2b110 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
2b120 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2b130 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
2b140 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
2b150 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
2b160 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
2b170 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
2b180 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
2b190 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
2b1a0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
2b1b0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2b1c0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
2b1d0 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75   ^The sixth argu
2b1e0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2b1f0 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75  bind_text64() mu
2b200 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  st be one of.** 
2b210 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
2b220 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
2b230 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2b240 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2b250 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69  6LE].** to speci
2b260 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  fy the encoding 
2b270 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74  of the text in t
2b280 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2b290 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73  er.  If.** the s
2b2a0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2b2b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2b2c0 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e  xt64() is not on
2b2d0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f  e of the.** allo
2b2e0 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e  wed values shown
2b2f0 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68   above, or if th
2b300 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2b310 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  is different.** 
2b320 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e  from the encodin
2b330 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  g specified by t
2b340 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
2b350 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  er, then the beh
2b360 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
2b370 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2b380 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
2b390 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
2b3a0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
2b3b0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
2b3c0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
2b3d0 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
2b3e0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
2b3f0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
2b400 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
2b410 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
2b420 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
2b430 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
2b440 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
2b450 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
2b460 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
2b470 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
2b480 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
2b490 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
2b4a0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
2b4b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
2b4c0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
2b4d0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
2b4e0 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
2b4f0 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
2b500 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
2b510 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
2b520 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
2b530 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
2b540 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2b550 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2b560 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
2b570 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
2b580 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b590 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
2b5a0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2b5b0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
2b5c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2b5d0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
2b5e0 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
2b5f0 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
2b600 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
2b610 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
2b620 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
2b630 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
2b640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
2b650 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
2b660 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
2b670 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2b680 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2b690 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
2b6a0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
2b6b0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
2b6c0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
2b6d0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
2b6e0 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
2b6f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
2b700 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
2b710 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
2b720 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
2b730 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2b740 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2b750 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2b760 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2b770 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
2b780 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
2b790 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
2b7a0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
2b7b0 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20  E_TOOBIG] might 
2b7c0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
2b7d0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72  he size of a str
2b7e0 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65  ing or BLOB.** e
2b7f0 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d  xceeds limits im
2b800 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  posed by [sqlite
2b810 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2b820 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20  _LIMIT_LENGTH]) 
2b830 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  or.** [SQLITE_MA
2b840 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b  X_LENGTH]..** ^[
2b850 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
2b860 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
2b870 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
2b880 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2b890 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
2b8a0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
2b8b0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
2b8c0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
2b8d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2b8e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b8f0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
2b900 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b910 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
2b920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b930 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2b940 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b950 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
2b960 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b970 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
2b980 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2b990 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b9a0 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ind_blob64(sqlit
2b9b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b9c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69  onst void*, sqli
2b9d0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2b9e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b9f0 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2ba00 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2ba10 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
2ba20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2ba30 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
2ba40 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
2ba50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ba60 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
2ba70 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
2ba80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ba90 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
2baa0 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
2bab0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
2bac0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
2bad0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2bae0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2baf0 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  t*,int,const cha
2bb00 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  r*,int,void(*)(v
2bb10 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2bb20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2bb30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2bb40 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2bb50 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2bb60 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2bb70 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73  e3_bind_text64(s
2bb80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2bb90 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
2bba0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
2bbb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bbc0 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2bbd0 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65  (void*), unsigne
2bbe0 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29  d char encoding)
2bbf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2bc00 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
2bc10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2bc20 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
2bc30 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2bc40 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
2bc50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2bc60 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71  , int n);.int sq
2bc70 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2bc80 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2bc90 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2bca0 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  3_uint64);../*.*
2bcb0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2bcc0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2bcd0 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ters.** METHOD: 
2bce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2bcf0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2bd00 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2bd10 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2bd20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2bd30 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2bd40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bd50 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2bd60 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2bd70 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2bd80 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2bd90 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2bda0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2bdb0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2bdc0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2bdd0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2bde0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2bdf0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2be00 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2be10 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2be20 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2be30 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2be40 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2be50 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2be60 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2be70 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2be80 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2be90 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2bea0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2beb0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2bec0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2bed0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2bee0 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2bef0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2bf00 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2bf10 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2bf20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2bf30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2bf40 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2bf50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bf60 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2bf70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2bf80 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2bf90 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2bfa0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bfb0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
2bfc0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2bfd0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2bfe0 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
2bff0 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ter.** METHOD: s
2c000 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c010 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2c020 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2c030 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
2c040 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
2c050 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
2c060 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
2c070 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
2c080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2c090 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
2c0a0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2c0b0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2c0c0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2c0d0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
2c0e0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
2c0f0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
2c100 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2c110 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2c120 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2c130 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2c140 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
2c150 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
2c160 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
2c170 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
2c180 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
2c190 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
2c1a0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
2c1b0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
2c1c0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
2c1d0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
2c1e0 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
2c1f0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
2c200 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
2c210 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
2c220 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
2c230 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2c240 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
2c250 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
2c260 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
2c270 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
2c280 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
2c290 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
2c2a0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
2c2b0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
2c2c0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
2c2d0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
2c2e0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
2c2f0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
2c300 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
2c310 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
2c320 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
2c330 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c340 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
2c350 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2c360 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2c370 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2c380 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2c390 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2c3a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c3b0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2c3c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2c3d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2c3e0 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
2c3f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
2c400 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2c410 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c420 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2c430 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2c440 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2c450 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2c460 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c470 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2c480 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2c490 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2c4a0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2c4b0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2c4c0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2c4d0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2c4e0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2c4f0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2c500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2c510 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2c520 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2c530 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2c540 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2c550 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2c560 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2c570 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2c580 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2c590 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2c5a0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2c5b0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2c5c0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2c5d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2c5e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2c5f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2c600 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c610 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2c620 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c630 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c640 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2c650 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c660 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2c670 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c680 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c690 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
2c6a0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
2c6b0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
2c6c0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2c6d0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
2c6e0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2c6f0 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2c700 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c710 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2c720 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2c730 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2c740 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2c750 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2c760 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c770 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2c780 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c790 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2c7a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2c7b0 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2c7c0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2c7d0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
2c7e0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2c7f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
2c800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c810 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
2c820 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
2c830 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
2c840 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c850 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
2c860 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c870 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2c880 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
2c890 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2c8a0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
2c8b0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2c8c0 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
2c8d0 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
2c8e0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
2c8f0 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
2c900 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
2c910 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
2c920 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2c930 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
2c940 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2c950 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
2c960 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c980 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
2c990 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2c9a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2c9b0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2c9c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2c9d0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
2c9e0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
2c9f0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
2ca00 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2ca10 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2ca20 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
2ca30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2ca40 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
2ca50 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2ca60 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2ca70 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2ca80 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
2ca90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2caa0 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
2cab0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2cac0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2cad0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
2cae0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
2caf0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
2cb00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cb10 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
2cb20 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
2cb30 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
2cb40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2cb50 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2cb60 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2cb70 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2cb80 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2cb90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2cba0 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2cbb0 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2cbc0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2cbd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cbe0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2cbf0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2cc00 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2cc10 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2cc20 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2cc30 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2cc40 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2cc50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2cc60 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2cc70 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2cc80 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2cc90 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2cca0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2ccb0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2ccc0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2ccd0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2cce0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2ccf0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2cd00 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2cd10 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2cd20 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2cd30 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2cd40 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2cd50 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2cd60 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2cd70 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2cd80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2cd90 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2cda0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2cdb0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2cdc0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2cdd0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2cde0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2cdf0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2ce00 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2ce10 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2ce20 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2ce30 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2ce40 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2ce50 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2ce60 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2ce70 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
2ce80 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2ce90 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2cea0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ceb0 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
2cec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2ced0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2cee0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
2cef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
2cf00 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
2cf10 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2cf20 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2cf30 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2cf40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
2cf50 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
2cf60 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
2cf70 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2cf80 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
2cf90 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
2cfa0 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
2cfb0 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
2cfc0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
2cfd0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
2cfe0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2cff0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
2d000 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
2d010 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
2d020 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
2d030 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
2d040 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
2d050 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
2d060 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
2d070 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
2d080 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
2d090 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
2d0a0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
2d0b0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
2d0c0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
2d0d0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
2d0e0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2d0f0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
2d100 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
2d110 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
2d120 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
2d130 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2d140 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2d150 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2d160 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2d170 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2d180 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2d190 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2d1a0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2d1b0 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2d1c0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
2d1d0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
2d1e0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
2d1f0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
2d200 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
2d210 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
2d220 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
2d230 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
2d240 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
2d250 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
2d260 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
2d270 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2d280 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
2d290 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
2d2a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d2b0 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
2d2c0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
2d2d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2d2e0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
2d2f0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2d300 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
2d310 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
2d320 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
2d330 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
2d340 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
2d350 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
2d360 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
2d370 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
2d380 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2d390 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
2d3a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
2d3b0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
2d3c0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
2d3d0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
2d3e0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
2d3f0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2d400 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
2d410 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
2d420 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
2d430 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
2d440 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2d450 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
2d460 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
2d470 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
2d480 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
2d490 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
2d4a0 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
2d4b0 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
2d4c0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
2d4d0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
2d4e0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
2d4f0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
2d500 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
2d510 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
2d520 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
2d530 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
2d540 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
2d550 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
2d560 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
2d570 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
2d580 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2d590 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2d5a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2d5b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2d5c0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2d5d0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2d5e0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
2d5f0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2d600 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2d610 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2d620 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
2d630 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
2d640 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
2d650 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
2d660 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2d670 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2d680 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
2d690 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
2d6a0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2d6b0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2d6c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2d6d0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2d6e0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
2d6f0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
2d700 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2d710 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d720 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
2d730 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
2d740 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2d750 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2d760 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
2d770 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2d780 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2d790 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
2d7a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2d7b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d7c0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2d7d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2d7e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2d7f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d800 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2d810 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d820 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2d830 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d840 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2d850 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d860 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2d870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2d880 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
2d890 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2d8a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d8b0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2d8c0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2d8d0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2d8e0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2d8f0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2d900 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2d910 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2d920 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
2d930 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d940 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2d950 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2d960 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2d970 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2d980 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2d990 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2d9a0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2d9b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2d9c0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2d9d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2d9e0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2d9f0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2da00 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2da10 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2da20 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2da30 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2da40 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2da50 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2da60 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2da70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2da80 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2da90 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2daa0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2dab0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2dac0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2dad0 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2dae0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2daf0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2db00 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2db10 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2db20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2db30 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2db40 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2db50 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2db60 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2db70 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2db80 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2db90 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2dba0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2dbb0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2dbc0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2dbd0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2dbe0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2dbf0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2dc00 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2dc10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2dc20 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2dc30 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2dc40 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2dc50 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2dc60 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2dc70 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2dc80 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2dc90 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2dca0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2dcb0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2dcc0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2dcd0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2dce0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2dcf0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2dd00 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2dd10 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2dd20 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2dd30 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2dd40 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2dd50 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2dd60 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2dd70 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2dd80 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2dd90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2dda0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2ddb0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2ddc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2ddd0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
2dde0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ddf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2de00 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
2de10 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
2de20 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2de30 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  _stmt.**.** Afte
2de40 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
2de50 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
2de60 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
2de70 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
2de80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2de90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2dea0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2deb0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
2dec0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
2ded0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dee0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
2def0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
2df00 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2df10 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
2df20 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2df30 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
2df40 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
2df50 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
2df60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2df70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2df80 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
2df90 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
2dfa0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
2dfb0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
2dfc0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
2dfd0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
2dfe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2dff0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2e000 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2e010 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
2e020 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2e030 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
2e040 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2e050 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2e060 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
2e070 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
2e080 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2e090 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
2e0a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
2e0b0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
2e0c0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
2e0d0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
2e0e0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
2e0f0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2e100 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
2e110 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
2e120 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
2e130 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
2e140 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
2e150 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
2e160 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
2e170 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
2e180 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
2e190 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
2e1a0 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
2e1b0 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
2e1c0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2e1d0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
2e1e0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
2e1f0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2e200 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
2e210 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
2e220 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
2e230 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
2e240 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
2e250 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
2e260 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
2e270 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2e280 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
2e290 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
2e2a0 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
2e2b0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
2e2c0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
2e2d0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
2e2e0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
2e2f0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
2e300 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
2e310 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
2e320 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2e330 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
2e340 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
2e350 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
2e360 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
2e370 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2e380 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
2e390 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2e3a0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
2e3b0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
2e3c0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
2e3d0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2e3e0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2e3f0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
2e400 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
2e410 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
2e420 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2e430 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
2e440 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
2e450 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
2e460 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
2e470 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
2e480 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
2e490 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
2e4a0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
2e4b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
2e4c0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
2e4d0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
2e4e0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
2e4f0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
2e500 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
2e510 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
2e520 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
2e530 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
2e540 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2e550 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
2e560 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
2e570 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
2e580 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
2e590 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
2e5a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
2e5b0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
2e5c0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
2e5d0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
2e5e0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
2e5f0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
2e600 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2e610 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2e620 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
2e630 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
2e640 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
2e650 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
2e660 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
2e670 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
2e680 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2e690 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
2e6a0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
2e6b0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
2e6c0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
2e6d0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2e6e0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
2e6f0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
2e700 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
2e710 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
2e720 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e730 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
2e740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e750 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
2e760 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
2e770 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2e780 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
2e790 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
2e7a0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2e7b0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
2e7c0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
2e7d0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
2e7e0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
2e7f0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
2e800 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
2e810 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
2e820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e830 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
2e840 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
2e850 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2e860 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
2e870 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
2e880 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
2e890 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
2e8a0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
2e8b0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
2e8c0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
2e8d0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
2e8e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2e8f0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
2e900 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
2e910 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
2e920 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
2e930 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
2e940 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
2e950 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
2e960 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
2e970 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
2e980 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
2e990 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
2e9a0 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
2e9b0 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
2e9c0 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
2e9d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2e9e0 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
2e9f0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2ea00 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
2ea10 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
2ea20 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
2ea30 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2ea40 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
2ea50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ea60 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
2ea70 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
2ea80 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
2ea90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2eaa0 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
2eab0 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
2eac0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2ead0 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
2eae0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2eaf0 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
2eb00 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
2eb10 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
2eb20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
2eb30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2eb40 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
2eb50 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
2eb60 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
2eb70 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
2eb80 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
2eb90 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
2eba0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
2ebb0 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
2ebc0 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
2ebd0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2ebe0 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
2ebf0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
2ec00 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
2ec10 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
2ec20 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
2ec30 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
2ec40 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
2ec50 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
2ec60 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2ec70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
2ec80 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
2ec90 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
2eca0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
2ecb0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
2ecc0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
2ecd0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
2ece0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
2ecf0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2ed00 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
2ed10 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2ed20 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2ed30 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
2ed40 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
2ed50 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
2ed60 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2ed70 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
2ed80 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2ed90 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
2eda0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
2edb0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
2edc0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
2edd0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
2ede0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2edf0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
2ee00 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
2ee10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
2ee20 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
2ee30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ee40 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2ee50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2ee60 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
2ee70 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
2ee80 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2ee90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2eea0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
2eeb0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
2eec0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
2eed0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
2eee0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2eef0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
2ef00 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
2ef10 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
2ef20 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2ef30 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
2ef40 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2ef50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2ef60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2ef70 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2ef80 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2ef90 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2efa0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2efb0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2efc0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
2efd0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2efe0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2eff0 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2f000 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2f010 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2f020 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f030 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2f040 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2f050 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2f060 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2f070 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2f080 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2f090 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2f0a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2f0b0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2f0c0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2f0d0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2f0e0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2f0f0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2f100 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2f110 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2f120 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2f130 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2f140 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2f150 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2f160 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2f170 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2f180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2f190 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2f1a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2f1b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2f1c0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2f1d0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2f1e0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2f1f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2f200 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2f210 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2f220 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2f230 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2f240 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2f250 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2f260 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2f270 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2f280 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2f290 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2f2a0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2f2b0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2f2c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2f2d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f2e0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2f2f0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2f300 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2f310 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2f320 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2f330 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2f340 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2f350 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2f360 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2f370 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2f380 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2f390 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2f3a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2f3b0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2f3c0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2f3d0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2f3e0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2f3f0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2f400 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2f410 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2f420 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2f430 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2f440 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2f450 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2f460 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2f470 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2f480 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2f490 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2f4a0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2f4b0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2f4c0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2f4d0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2f4e0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2f4f0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2f500 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2f510 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2f520 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2f530 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2f540 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2f550 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2f560 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2f570 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2f580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2f590 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2f5a0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2f5b0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2f5c0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2f5d0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2f5e0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2f5f0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2f600 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2f610 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2f620 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2f630 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2f640 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2f650 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2f660 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2f670 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f680 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2f690 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2f6a0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2f6b0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
2f6c0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
2f6d0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
2f6e0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
2f6f0 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
2f700 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2f710 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2f720 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2f730 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2f740 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2f750 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2f760 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2f770 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2f780 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2f790 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2f7a0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2f7b0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2f7c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2f7d0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2f7e0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2f7f0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2f800 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2f810 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
2f820 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2f830 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2f840 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2f850 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
2f860 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2f870 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
2f880 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
2f890 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2f8a0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
2f8b0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2f8c0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2f8d0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2f8e0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2f8f0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2f900 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2f910 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2f920 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2f930 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2f940 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2f950 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2f960 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2f970 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2f980 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2f990 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2f9a0 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2f9b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2f9c0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2f9d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2f9e0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2f9f0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2fa00 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2fa10 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2fa20 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2fa30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2fa40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2fa50 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2fa60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fa70 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2fa80 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2fa90 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2faa0 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2fab0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2fac0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2fad0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2fae0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2faf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2fb00 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2fb10 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2fb20 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2fb30 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2fb40 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2fb50 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2fb60 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2fb70 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2fb80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fb90 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
2fba0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
2fbb0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2fbc0 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
2fbd0 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
2fbe0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
2fbf0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
2fc00 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2fc10 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
2fc20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2fc30 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
2fc40 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2fc50 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
2fc60 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
2fc70 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
2fc80 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2fc90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fca0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
2fcb0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
2fcc0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
2fcd0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
2fce0 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
2fcf0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
2fd00 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
2fd10 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
2fd20 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2fd30 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2fd40 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
2fd50 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
2fd60 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
2fd70 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
2fd80 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
2fd90 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
2fda0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
2fdb0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
2fdc0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2fdd0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2fde0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2fdf0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2fe00 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2fe10 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2fe20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2fe30 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2fe40 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2fe50 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2fe60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
2fe70 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2fe80 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
2fe90 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2fea0 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
2feb0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2fec0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2fed0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fee0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2fef0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2ff00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ff10 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2ff20 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2ff30 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2ff40 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
2ff50 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2ff60 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2ff70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2ff80 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2ff90 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2ffa0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2ffb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ffc0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2ffd0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2ffe0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2fff0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
30000 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
30010 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30020 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
30030 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
30040 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
30050 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
30060 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
30070 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
30080 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
30090 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
300a0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
300b0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
300c0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
300d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
300e0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
300f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
30100 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
30110 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
30120 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
30130 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
30140 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
30150 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
30160 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
30170 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
30180 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
30190 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
301a0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
301b0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
301c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
301d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
301e0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
301f0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
30200 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
30210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30220 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
30230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30240 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
30250 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
30260 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
30270 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
30280 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
30290 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
302a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
302b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
302c0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
302d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
302e0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
302f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
30300 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
30310 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
30320 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
30330 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
30340 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
30350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30360 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
30370 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
30380 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
30390 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
303a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
303b0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
303c0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
303d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
303e0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
303f0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
30400 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
30410 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
30420 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
30430 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
30440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
30450 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
30460 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30470 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
30480 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
30490 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
304a0 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
304b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
304c0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
304d0 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
304e0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
304f0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
30500 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
30510 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
30520 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
30530 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30540 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
30550 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
30560 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
30570 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
30580 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
30590 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
305a0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
305b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
305c0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
305d0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
305e0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
305f0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
30600 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
30610 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
30620 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
30630 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
30640 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
30650 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
30660 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
30670 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
30680 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
30690 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
306a0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
306b0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
306c0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
306d0 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
306e0 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
306f0 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
30700 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
30710 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
30720 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
30730 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
30740 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
30750 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
30760 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
30770 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
30780 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
30790 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
307a0 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
307b0 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
307c0 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
307d0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
307e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
307f0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
30800 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
30810 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
30820 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
30830 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
30840 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
30850 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
30860 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
30870 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
30880 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
30890 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
308a0 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
308b0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
308c0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
308d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
308e0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
308f0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
30900 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
30910 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
30920 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
30930 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
30940 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
30950 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
30960 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
30970 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
30980 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
30990 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
309a0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
309b0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
309c0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
309d0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
309e0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
309f0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
30a00 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
30a10 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
30a20 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
30a30 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42  > [CAST] to BLOB
30a40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
30a50 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
30a60 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
30a70 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
30a80 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
30a90 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
30aa0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
30ab0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
30ac0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
30ad0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
30ae0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
30af0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
30b00 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
30b10 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
30b20 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  R.** <tr><td>  B
30b30 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
30b40 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
30b50 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
30b60 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
30b70 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
30b80 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
30b90 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
30ba0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
30bb0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
30bc0 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ^.**.** Note tha
30bd0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
30be0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
30bf0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
30c00 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
30c10 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
30c20 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
30c30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30c40 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
30c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30c60 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
30c70 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
30c80 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
30c90 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
30ca0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
30cb0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
30cc0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
30cd0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
30ce0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
30cf0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
30d00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
30d10 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
30d20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
30d30 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
30d40 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
30d50 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
30d60 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
30d70 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
30d80 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
30d90 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
30da0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
30db0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
30dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30dd0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
30de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30df0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
30e00 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
30e10 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
30e20 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
30e30 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
30e40 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
30e50 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
30e60 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
30e70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
30e80 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30e90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30ea0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
30eb0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
30ec0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
30ed0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
30ee0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
30ef0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
30f00 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
30f10 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
30f20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
30f30 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
30f40 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
30f50 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
30f60 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
30f70 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
30f80 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
30f90 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
30fa0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
30fb0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
30fc0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
30fd0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
30fe0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
30ff0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
31000 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
31010 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
31020 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
31030 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
31040 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
31050 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
31060 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
31070 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69   safest policy i
31080 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
31090 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
310a0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
310b0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
310c0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
310d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
310e0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
310f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31100 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
31110 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
31120 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
31130 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
31140 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
31150 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
31160 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
31170 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
31180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31190 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
311a0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
311b0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
311c0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
311d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
311e0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
311f0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
31200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31210 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
31220 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
31230 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
31240 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
31250 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
31260 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
31270 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
31280 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
31290 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
312a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
312b0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
312c0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
312d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
312e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
312f0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
31300 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
31310 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31320 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
31330 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
31340 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
31350 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
31360 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
31370 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
31380 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
31390 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
313a0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
313b0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
313c0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
313d0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
313e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
313f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
31400 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
31410 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31420 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
31430 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
31440 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
31450 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
31460 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
31470 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65  atically.  Do <e
31480 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20  m>not</em> pass 
31490 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
314a0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
314b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
314c0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
314d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
314e0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
314f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
31500 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
31510 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
31520 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
31530 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
31540 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
31550 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
31560 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
31570 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
31580 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
31590 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
315a0 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
315b0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
315c0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
315d0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
315e0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
315f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
31600 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
31610 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
31620 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
31630 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31640 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
31650 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31660 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
31670 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
31680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31690 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
316a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
316b0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
316c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
316d0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
316e0 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
316f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31700 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
31710 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
31720 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31730 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
31740 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
31750 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
31760 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31770 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
31780 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
31790 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
317a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
317b0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
317c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
317d0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
317e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
317f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
31800 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
31810 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31820 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
31830 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
31840 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
31850 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31860 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31870 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
31880 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
31890 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
318a0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
318b0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
318c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
318d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
318e0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
318f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31900 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
31910 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
31920 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
31930 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
31940 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
31950 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
31960 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
31970 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
31980 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
31990 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
319a0 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
319b0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
319c0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
319d0 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
319e0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
319f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
31a00 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
31a10 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
31a20 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
31a30 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
31a40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31a50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
31a60 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
31a70 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
31a80 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
31a90 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
31aa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31ab0 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
31ac0 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
31ad0 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
31ae0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
31af0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
31b00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31b10 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
31b20 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
31b30 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
31b40 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
31b50 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
31b60 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
31b70 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
31b80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
31b90 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
31ba0 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
31bb0 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
31bc0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
31bd0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
31be0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
31bf0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
31c00 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
31c10 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
31c20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
31c30 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
31c40 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
31c50 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
31c60 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
31c70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31c80 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
31c90 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
31ca0 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
31cb0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
31cc0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
31cd0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
31ce0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
31cf0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
31d00 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
31d10 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
31d20 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
31d30 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
31d40 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
31d50 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
31d60 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31d70 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
31d80 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
31d90 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45  ent Object.** ME
31da0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31db0 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  mt.**.** The sql
31dc0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
31dd0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
31de0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
31df0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
31e00 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
31e10 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
31e20 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
31e30 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
31e40 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
31e50 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
31e60 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
31e70 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
31e80 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
31e90 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
31ea0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
31eb0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
31ec0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
31ed0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
31ee0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
31ef0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
31f00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
31f10 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
31f20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
31f30 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31f40 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
31f50 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
31f60 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
31f70 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
31f80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
31f90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31fa0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
31fb0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
31fc0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
31fd0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
31fe0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
31ff0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
32000 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
32010 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
32020 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
32030 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
32040 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
32050 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
32060 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
32070 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
32080 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
32090 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
320a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
320b0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
320c0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
320d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
320e0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
320f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
32100 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
32110 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
32120 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
32130 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
32140 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
32150 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
32160 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
32170 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
32180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32190 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
321a0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
321b0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
321c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
321d0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
321e0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
321f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
32200 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
32210 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
32220 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
32230 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
32240 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
32250 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
32260 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
32270 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
32280 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
32290 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
322a0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
322b0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
322c0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
322d0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
322e0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
322f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
32300 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
32310 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
32320 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
32330 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
32340 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
32350 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
32360 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
32370 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
32380 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
32390 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
323a0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
323b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
323c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
323d0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
323e0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
323f0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
32400 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
32410 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
32420 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
32430 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
32440 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
32450 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
32460 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32470 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
32480 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
32490 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
324a0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
324b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
324c0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
324d0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
324e0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
324f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
32500 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
32510 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
32520 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
32530 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
32540 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
32550 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
32560 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
32570 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32580 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
32590 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
325a0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
325b0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
325c0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
325d0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
325e0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
325f0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
32600 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
32610 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
32620 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
32630 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
32640 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
32650 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
32660 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
32670 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
32680 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
32690 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
326a0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
326b0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
326c0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
326d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
326e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
326f0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
32700 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
32710 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
32720 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
32730 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
32740 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
32750 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
32760 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
32770 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32780 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
32790 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
327a0 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
327b0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
327c0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
327d0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
327e0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
327f0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
32800 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
32810 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
32820 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
32830 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
32840 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
32850 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
32860 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
32870 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
32880 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
32890 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
328a0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
328b0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
328c0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
328d0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
328e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
328f0 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
32900 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
32910 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
32920 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
32930 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32940 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
32950 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32960 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
32970 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
32980 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
32990 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
329a0 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
329b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
329c0 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
329d0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
329e0 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
329f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
32a00 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
32a10 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
32a20 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
32a30 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
32a40 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
32a50 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
32a60 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
32a70 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
32a80 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
32a90 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
32aa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
32ab0 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
32ac0 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
32ad0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
32ae0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
32af0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
32b00 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
32b10 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
32b20 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
32b30 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
32b40 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
32b50 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
32b60 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
32b70 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
32b80 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
32b90 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
32ba0 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
32bb0 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
32bc0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
32bd0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
32be0 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
32bf0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
32c00 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
32c10 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
32c20 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
32c30 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
32c40 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
32c50 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
32c60 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
32c70 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
32c80 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
32c90 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
32ca0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
32cb0 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
32cc0 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
32cd0 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
32ce0 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
32cf0 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
32d00 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
32d10 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
32d20 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
32d30 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
32d40 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
32d50 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
32d60 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
32d70 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
32d80 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
32d90 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
32da0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
32db0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
32dc0 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
32dd0 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
32de0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
32df0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
32e00 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
32e10 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
32e20 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
32e30 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
32e40 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
32e50 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
32e60 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
32e70 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
32e80 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32e90 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
32ea0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
32eb0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
32ec0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32ed0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
32ee0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
32ef0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
32f00 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
32f10 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
32f20 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
32f30 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
32f40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32f50 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32f60 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
32f70 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
32f80 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
32f90 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
32fa0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
32fb0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
32fc0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
32fd0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
32fe0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
32ff0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
33000 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
33010 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
33020 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
33030 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
33040 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
33050 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
33060 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
33070 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
33080 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
33090 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
330a0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
330b0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
330c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
330d0 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
330e0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
330f0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
33100 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
33110 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
33120 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
33130 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
33140 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
33150 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
33160 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
33170 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
33180 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
33190 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
331a0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
331b0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
331c0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
331d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
331e0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
331f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33200 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
33210 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
33220 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
33230 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
33240 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
33250 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
33260 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
33270 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
33280 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
33290 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
332a0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
332b0 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
332c0 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
332d0 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
332e0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
332f0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
33300 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
33310 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
33320 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
33330 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
33340 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
33350 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
33360 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
33370 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
33380 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
33390 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
333a0 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
333b0 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
333c0 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
333d0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
333e0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
333f0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
33400 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
33410 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
33420 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
33430 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
33440 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
33450 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
33460 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
33470 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
33480 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
33490 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
334a0 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
334b0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
334c0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
334d0 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
334e0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
334f0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
33500 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
33510 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
33520 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
33530 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
33540 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
33550 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
33560 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
33570 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
33580 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
33590 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
335a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
335b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
335c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
335d0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
335e0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
335f0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
33600 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
33610 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
33620 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
33630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
33640 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
33650 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
33660 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
33670 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
33680 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
33690 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
336a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
336b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
336c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
336d0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
336e0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
336f0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
33700 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
33710 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
33720 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
33730 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
33740 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
33750 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
33760 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
33770 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
33780 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
33790 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
337a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
337b0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
337c0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
337d0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
337e0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
337f0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
33800 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
33810 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
33820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33830 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
33840 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
33850 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
33860 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
33870 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
33880 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
33890 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
338a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
338b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
338c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
338d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
338e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
338f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
33900 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
33910 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
33920 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
33930 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
33940 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
33950 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
33960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33970 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33980 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33990 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
339a0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
339b0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
339c0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
339d0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
339e0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
339f0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
33a00 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
33a10 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
33a20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
33a30 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
33a40 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
33a50 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
33a60 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
33a70 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a      1    /* IMP:
33a80 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a   R-37514-35566 *
33a90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33aa0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
33ab0 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30  2    /* IMP: R-0
33ac0 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64  3371-37637 */.#d
33ad0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
33ae0 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20  16BE        3   
33af0 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31   /* IMP: R-51971
33b00 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e  -34154 */.#defin
33b10 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
33b20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
33b30 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
33b40 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
33b50 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
33b60 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44         5    /* D
33b70 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65  eprecated */.#de
33b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
33b90 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
33ba0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
33bb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
33bc0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
33bd0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c  REF: Function Fl
33be0 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
33bf0 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
33c00 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77   ORed together w
33c10 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
33c20 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65  ITE_UTF8 | prefe
33c30 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
33c40 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74  ng] as the fourt
33c50 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
33c60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33c70 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73  _function()], [s
33c80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33c90 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  nction16()], or.
33ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
33cb0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
33cc0 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
33cd0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
33ce0 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a  IC    0x800../*.
33cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
33d00 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
33d10 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
33d20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
33d30 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
33d40 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
33d50 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
33d60 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
33d70 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
33d80 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
33d90 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
33da0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
33db0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
33dc0 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
33dd0 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
33de0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
33df0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
33e00 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f  To encourage pro
33e10 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69  grammers to avoi
33e20 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  d.** these funct
33e30 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f  ions, we will no
33e40 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74  t explain what t
33e50 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
33e60 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
33e70 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
33e80 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
33e90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33ea0 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
33eb0 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
33ec0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33ed0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
33ee0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
33ef0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
33f00 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
33f10 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
33f20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33f30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
33f40 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33f50 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
33f60 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
33f70 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
33f80 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
33f90 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
33fa0 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
33fb0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
33fc0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
33fd0 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
33fe0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
33ff0 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
34000 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
34010 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
34020 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
34030 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
34040 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ing SQL Values.*
34050 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34060 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
34070 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
34080 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
34090 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
340a0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
340b0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
340c0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
340d0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
340e0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
340f0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
34100 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
34110 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  e.  .**.** The x
34120 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
34130 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
34140 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
34150 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
34160 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
34170 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34180 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34190 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
341a0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
341b0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
341c0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
341d0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
341e0 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
341f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
34200 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
34210 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
34220 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
34230 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
34240 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34250 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
34260 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34270 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
34280 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
34290 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
342a0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
342b0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
342c0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
342d0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
342e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
342f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
34300 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
34310 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
34320 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34330 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
34340 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
34350 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
34360 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
34370 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34380 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
34390 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
343a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
343b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
343c0 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
343d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
343e0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
343f0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
34400 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20  cept that these 
34410 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
34420 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
34430 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34440 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
34450 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
34460 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
34470 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
34480 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
34490 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
344a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
344b0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
344c0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
344d0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
344e0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
344f0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
34500 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
34510 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
34520 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
34530 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
34540 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
34550 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
34560 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
34570 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
34580 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
34590 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
345a0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
345b0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
345c0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
345d0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
345e0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
345f0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
34600 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
34610 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
34620 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
34630 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
34640 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
34650 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
34660 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
34670 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
34680 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
34690 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
346a0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
346b0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
346c0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
346d0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
346e0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
346f0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
34700 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
34710 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
34720 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
34730 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
34740 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
34750 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
34760 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
34770 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
34780 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
34790 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
347a0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
347b0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
347c0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
347d0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
347e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
347f0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
34800 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34810 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
34820 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
34830 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
34840 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
34850 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
34860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
34870 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
34880 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
34890 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
348a0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
348b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
348c0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
348d0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
348e0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
348f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34900 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
34910 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34920 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
34930 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
34940 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
34950 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34960 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
34970 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
34980 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
34990 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
349a0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
349b0 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
349c0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
349d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
349e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
349f0 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
34a00 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
34a10 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
34a20 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
34a30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
34a40 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
34a50 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
34a60 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
34a70 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
34a80 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
34a90 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
34aa0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
34ab0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
34ac0 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
34ad0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
34ae0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
34af0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
34b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34b10 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
34b20 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
34b30 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
34b40 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
34b50 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
34b60 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
34b70 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67  API3REF: Finding
34b80 20 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20   The Subtype Of 
34b90 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
34ba0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
34bb0 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  lue.**.** The sq
34bc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74  lite3_value_subt
34bd0 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20  ype(V) function 
34be0 72 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74  returns the subt
34bf0 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61  ype for.** an [a
34c00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34c10 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
34c20 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68   argument V.  Th
34c30 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66  e subtype.** inf
34c40 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20  ormation can be 
34c50 75 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c  used to pass a l
34c60 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66  imited amount of
34c70 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a   context from.**
34c80 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   one SQL functio
34c90 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55  n to another.  U
34ca0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
34cb0 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29  result_subtype()
34cc0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  ].** routine to 
34cd0 73 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20  set the subtype 
34ce0 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76  for the return v
34cf0 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66  alue of an SQL f
34d00 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  unction..**.** S
34d10 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75  QLite makes no u
34d20 73 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74  se of subtype it
34d30 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79  self.  It merely
34d40 20 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74   passes the subt
34d50 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ype.** from the 
34d60 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61  result of one [a
34d70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34d80 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
34d90 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70   into the.** inp
34da0 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a  ut of another..*
34db0 2f 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  /.unsigned int s
34dc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62  qlite3_value_sub
34dd0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
34de0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
34df0 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20  I3REF: Copy And 
34e00 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a  Free SQL Values.
34e10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
34e20 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e  e3_value.**.** ^
34e30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
34e40 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61  e_dup(V) interfa
34e50 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
34e60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34e70 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
34e80 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61   D and returns a
34e90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
34ea0 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71   copy.  ^The [sq
34eb0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74  lite3_value] ret
34ec0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70  urned.** is a [p
34ed0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34ee0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65  _value] object e
34ef0 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74  ven if the input
34f00 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65   is not..** ^The
34f10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
34f20 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20  up(V) interface 
34f30 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
34f40 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20  V is NULL or if 
34f50 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
34f60 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a  cation fails..**
34f70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34f80 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69  _value_free(V) i
34f90 6e 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61  nterface frees a
34fa0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  n [sqlite3_value
34fb0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76  ] object.** prev
34fc0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
34fd0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
34fe0 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66  lue_dup()].  ^If
34ff0 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
35000 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  nter.** then sql
35010 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
35020 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  V) is a harmless
35030 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74   no-op..*/.sqlit
35040 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
35050 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73  3_value_dup(cons
35060 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
35070 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35080 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74  value_free(sqlit
35090 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
350a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
350b0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
350c0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
350d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
350e0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
350f0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
35100 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
35110 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
35120 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
35130 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
35140 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
35150 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
35160 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
35170 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
35180 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
35190 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
351a0 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
351b0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
351c0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
351d0 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
351e0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
351f0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
35200 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
35210 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
35220 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
35230 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
35240 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
35250 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
35260 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35270 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
35280 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
35290 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
352a0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
352b0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
352c0 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
352d0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
352e0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
352f0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
35300 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
35310 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
35320 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
35330 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
35340 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
35350 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
35360 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
35370 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
35380 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
35390 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
353a0 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
353b0 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
353c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
353d0 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
353e0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
353f0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
35400 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
35410 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
35420 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35430 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
35440 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
35450 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
35460 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
35470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35480 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35490 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
354a0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
354b0 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
354c0 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
354d0 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
354e0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
354f0 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
35500 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
35510 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
35520 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
35530 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
35540 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
35550 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
35560 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
35570 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
35580 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
35590 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
355a0 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
355b0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
355c0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
355d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
355e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
355f0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
35600 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
35610 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
35620 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
35630 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
35640 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
35650 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
35660 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
35670 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
35680 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
35690 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
356a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
356b0 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
356c0 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
356d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
356e0 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
356f0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
35700 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
35710 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
35720 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
35730 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
35740 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
35750 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
35760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
35770 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
35780 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
35790 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
357a0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
357b0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
357c0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
357d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
357e0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
357f0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
35800 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
35810 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
35820 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
35830 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
35840 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
35850 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
35860 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
35870 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
35880 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
35890 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
358a0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
358b0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
358c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
358d0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
358e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
358f0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
35900 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
35910 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
35920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35930 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
35940 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35950 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
35960 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
35970 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
35980 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
35990 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
359a0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
359b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
359c0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
359d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
359e0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
359f0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
35a00 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
35a10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35a20 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
35a30 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
35a40 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
35a50 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
35a60 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
35a70 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
35a80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35a90 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35aa0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
35ab0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
35ac0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
35ad0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35ae0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
35af0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
35b00 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
35b10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
35b20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35b30 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
35b40 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
35b50 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
35b60 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
35b70 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
35b80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
35b90 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
35ba0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
35bb0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
35bc0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
35bd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35be0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
35bf0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
35c00 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
35c10 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
35c20 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
35c30 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
35c40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
35c50 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
35c60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
35c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35c80 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
35c90 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f  ry Data.** METHO
35ca0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
35cb0 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  xt.**.** These f
35cc0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
35cd0 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
35ce0 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
35cf0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
35d00 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
35d10 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
35d20 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
35d30 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
35d40 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
35d50 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
35d60 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
35d70 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
35d80 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
35d90 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
35da0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
35db0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
35dc0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
35dd0 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
35de0 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
35df0 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
35e00 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
35e10 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
35e20 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
35e30 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
35e40 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
35e50 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
35e60 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
35e70 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
35e80 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35e90 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
35ea0 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
35eb0 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72  ng as the patter
35ec0 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73  n string remains
35ed0 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68   the same,.** th
35ee0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
35ef0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
35f00 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
35f10 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
35f20 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
35f30 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  me function..**.
35f40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35f50 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
35f60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35f70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35f80 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
35f90 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
35fa0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35fb0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
35fc0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
35fd0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
35fe0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35ff0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36000 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  . ^If there is n
36010 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  o metadata.** as
36020 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
36030 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  e function argum
36040 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65  ent, this sqlite
36050 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
36060 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
36070 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
36080 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
36090 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
360a0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74  ata(C,N,P,X) int
360b0 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61  erface saves P a
360c0 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  s metadata for t
360d0 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
360e0 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
360f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36100 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65  unction.  ^Subse
36110 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
36120 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
36130 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72  xdata(C,N) retur
36140 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73  n P from the mos
36150 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69  t recent.** sqli
36160 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36170 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66  C,N,P,X) call if
36180 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
36190 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a   still valid or.
361a0 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d  ** NULL if the m
361b0 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
361c0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e   discarded..** ^
361d0 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20  After each call 
361e0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
361f0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
36200 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e  where X is not N
36210 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ULL,.** SQLite w
36220 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
36230 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
36240 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65  on X with parame
36250 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a  ter P exactly.**
36260 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20   once, when the 
36270 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63  metadata is disc
36280 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  arded..** SQLite
36290 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63   is free to disc
362a0 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61  ard the metadata
362b0 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e   at any time, in
362c0 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a  cluding: <ul>.**
362d0 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63   <li> when the c
362e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
362f0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
36300 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c  changes, or.** <
36310 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  li> when [sqlite
36320 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
36330 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36340 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  )] is called for
36350 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c   the.**      SQL
36360 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a   statement, or.*
36370 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69  * <li> when sqli
36380 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36390 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61  ) is invoked aga
363a0 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70  in on the same p
363b0 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20  arameter, or.** 
363c0 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20  <li> during the 
363d0 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33  original sqlite3
363e0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63  _set_auxdata() c
363f0 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72  all when a memor
36400 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63  y .**      alloc
36410 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
36420 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  rs. </ul>)^.**.*
36430 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20  * Note the last 
36440 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63  bullet in partic
36450 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72  ular.  The destr
36460 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73  uctor X in .** s
36470 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
36480 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68  ta(C,N,P,X) migh
36490 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65  t be called imme
364a0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
364b0 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  the.** sqlite3_s
364c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
364d0 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75  erface even retu
364e0 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69  rns.  Hence sqli
364f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
36500 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63  ).** should be c
36510 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65  alled near the e
36520 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nd of the functi
36530 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
36540 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e  n and the.** fun
36550 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
36560 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
36570 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20  make any use of 
36580 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74  P after.** sqlit
36590 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
365a0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
365b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
365c0 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
365d0 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
365e0 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
365f0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74  lls for.** funct
36600 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ion parameters t
36610 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d  hat are compile-
36620 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20  time constants, 
36630 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61  including litera
36640 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
36650 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64  [parameters] and
36660 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d   expressions com
36670 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73  posed from the s
36680 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ame.)^.**.** The
36690 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
366a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
366b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
366c0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
366d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
366e0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
366f0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
36700 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
36710 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
36720 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
36730 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
36740 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
36750 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
36760 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
36770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
36780 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
36790 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
367a0 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
367b0 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
367c0 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
367d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
367e0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
367f0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
36800 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
36810 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
36820 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
36830 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
36840 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
36850 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
36860 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
36870 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
36880 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
36890 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
368a0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
368b0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
368c0 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
368d0 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
368e0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
368f0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
36900 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
36910 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
36920 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
36930 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
36940 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
36950 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
36960 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
36970 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
36980 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
36990 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
369a0 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
369b0 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
369c0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
369d0 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65  mpilers..*/.type
369e0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
369f0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
36a00 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
36a10 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
36a20 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
36a30 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
36a40 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
36a50 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
36a60 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
36a70 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
36a80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
36a90 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
36aa0 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
36ab0 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ion.** METHOD: s
36ac0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
36ad0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36ae0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
36af0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
36b00 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
36b10 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
36b20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
36b30 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
36b40 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
36b50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
36b60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
36b70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
36b80 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
36b90 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
36ba0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
36bb0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
36bc0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
36bd0 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
36be0 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
36bf0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
36c00 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
36c10 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
36c20 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
36c30 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
36c40 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
36c50 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
36c60 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
36c70 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
36c80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
36c90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36ca0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
36cb0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
36cc0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
36cd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36ce0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
36cf0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
36d00 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
36d10 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
36d20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
36d30 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
36d40 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
36d50 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
36d60 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
36d70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36d80 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c  sult_zeroblob(C,
36d90 4e 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  N) and sqlite3_r
36da0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34  esult_zeroblob64
36db0 28 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61  (C,N).** interfa
36dc0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
36dd0 6c 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  lt of the applic
36de0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36df0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
36e00 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
36e10 67 20 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73  g all zero bytes
36e20 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
36e30 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  size..**.** ^The
36e40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36e50 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
36e60 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
36e70 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
36e80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36e90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
36ea0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
36eb0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
36ec0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
36ed0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36ee0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36ef0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
36f00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36f10 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
36f20 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
36f30 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
36f40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
36f50 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
36f60 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
36f70 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
36f80 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
36f90 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
36fa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36fb0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
36fc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36fd0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
36fe0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
36ff0 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
37000 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
37010 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
37020 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
37030 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37040 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
37050 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
37060 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
37070 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
37080 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
37090 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
370a0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
370b0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
370c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
370d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
370e0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
370f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37100 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
37110 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
37120 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
37130 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
37140 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
37150 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
37160 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
37170 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
37180 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
37190 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
371a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
371b0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
371c0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
371d0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
371e0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
371f0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
37200 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
37210 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
37220 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
37230 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37240 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37250 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37260 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
37270 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
37280 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
37290 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
372a0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
372b0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
372c0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
372d0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
372e0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
372f0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
37300 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
37310 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
37320 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37330 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
37340 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
37350 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
37360 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
37370 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
37380 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
37390 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
373a0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
373b0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
373c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
373d0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
373e0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
373f0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
37400 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
37410 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
37420 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
37430 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
37440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37450 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37460 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
37470 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37480 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37490 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
374a0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
374b0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
374c0 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
374d0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
374e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
374f0 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
37500 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37510 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37520 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37530 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
37540 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
37550 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
37560 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
37570 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
37580 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
37590 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
375a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
375b0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
375c0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
375d0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
375e0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
375f0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37600 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37610 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
37620 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37630 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
37640 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37650 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37660 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
37670 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
37680 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
37690 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
376a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
376b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
376c0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
376d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
376e0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
376f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37700 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37710 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
37720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37730 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
37740 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37750 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
37760 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37770 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
37780 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
37790 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
377a0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
377b0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
377c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
377d0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
377e0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
377f0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
37800 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
37810 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
37820 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
37830 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
37840 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
37850 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
37860 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20  tively..** ^The 
37870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37880 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  ext64() interfac
37890 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
378a0 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a  n value of an.**
378b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
378c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
378d0 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e   be a text strin
378e0 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67  g in an encoding
378f0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79  .** specified by
37900 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20   the fifth (and 
37910 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c  last) parameter,
37920 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f   which must be o
37930 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45  ne.** of [SQLITE
37940 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
37950 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
37960 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
37970 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a  LITE_UTF16LE]..*
37980 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
37990 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
379a0 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
379b0 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
379c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
379d0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
379e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
379f0 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
37a00 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
37a10 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
37a20 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
37a30 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
37a40 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
37a50 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
37a60 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
37a70 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
37a80 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
37a90 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
37aa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
37ab0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
37ac0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37ad0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37ae0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
37af0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
37b00 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
37b10 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
37b20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
37b30 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
37b40 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
37b50 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
37b60 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
37b70 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
37b80 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72    If the 3rd par
37b90 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65  ameter is non-ne
37ba0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a  gative, then it.
37bb0 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  ** must be the b
37bc0 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20  yte offset into 
37bd0 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
37be0 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
37bf0 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70  tor would.** app
37c00 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e  ear if the strin
37c10 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d  g where NUL term
37c20 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
37c30 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
37c40 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73  ccur.** in the s
37c50 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20  tring at a byte 
37c60 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c  offset that is l
37c70 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c  ess than the val
37c80 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a  ue of the 3rd.**
37c90 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
37ca0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
37cb0 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61  tring will conta
37cc0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
37cd0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75   and the.** resu
37ce0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
37cf0 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73  s operating on s
37d00 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65  trings with embe
37d10 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
37d20 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  efined..** ^If t
37d30 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
37d40 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
37d50 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
37d60 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
37d70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
37d80 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
37d90 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
37da0 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
37db0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
37dc0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
37dd0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
37de0 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
37df0 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
37e00 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
37e10 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
37e20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
37e30 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37e40 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
37e50 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
37e60 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37e70 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
37e80 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
37e90 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
37ea0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
37eb0 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
37ec0 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
37ed0 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
37ee0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
37ef0 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
37f00 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
37f10 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
37f20 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
37f30 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
37f40 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
37f50 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
37f60 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
37f70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
37f80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37f90 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
37fa0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
37fb0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
37fc0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
37fd0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
37fe0 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
37ff0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
38000 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
38010 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
38020 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
38030 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
38040 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
38050 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
38060 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
38070 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
38080 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
38090 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
380a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
380b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
380c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
380d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
380e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
380f0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
38100 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38110 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
38120 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
38130 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
38140 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
38150 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
38160 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
38170 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
38180 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
38190 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
381a0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
381b0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
381c0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
381d0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
381e0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
381f0 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
38200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
38210 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
38220 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
38230 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
38240 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
38250 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
38260 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
38270 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
38280 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
38290 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
382a0 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
382b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
382c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
382d0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
382e0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
382f0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
38300 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
38310 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38320 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
38330 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
38340 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
38350 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
38360 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
38370 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
38380 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
38390 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
383a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
383b0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
383c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
383d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
383e0 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  t_blob64(sqlite3
383f0 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20  _context*,const 
38400 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20  void*,.         
38410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38420 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34    sqlite3_uint64
38430 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
38440 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
38450 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
38460 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
38470 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
38480 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
38490 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
384a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
384b0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
384c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
384d0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
384e0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
384f0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
38500 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
38510 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
38520 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
38530 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38540 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
38550 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
38560 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
38570 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
38580 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38590 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
385a0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
385b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
385c0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
385d0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
385e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
385f0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
38600 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
38610 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
38620 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
38630 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
38640 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
38650 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
38660 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
38670 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
38680 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38690 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63  text64(sqlite3_c
386a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
386b0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
386c0 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
386d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
386e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
386f0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
38700 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71  coding);.void sq
38710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
38720 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
38730 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
38740 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
38750 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
38760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
38770 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
38780 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
38790 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
387a0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
387b0 71 6c 69 74 65 3