/ Hex Artifact Content
Login

Artifact 7d87d71b9a4689c51fa092f48f16590ff71558e3:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20  _IOERR_VNODE    
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29  _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20  _IOERR_AUTH     
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29  _IOERR | (28<<8)
5610: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5620: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5630: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5640: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5660: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5670: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5680: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5690: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56a0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
56b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56c0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56f0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
5700: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5710: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
5730: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5740: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5750: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5760: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5770: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5780: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5790: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57b0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
57c0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57d0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57f0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5800: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5810: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5830: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5850: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5870: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5880: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5890: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
58a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58b0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
58d0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
5900: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
5910: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5930: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5940: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5950: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5980: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59c0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
59d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59e0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a00: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5a10: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5a20: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a50: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a90: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5aa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ab0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5ac0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ad0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5ae0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5af0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b10: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5b30: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b50: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b60: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ba0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5bb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bc0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5be0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c00: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c60: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c70: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c80: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5ca0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5cb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5cc0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ce0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5d00: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5d20: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5d30: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5dc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5de0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5e00: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5e10: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5e20: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e30: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e50: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e60: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e70: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e80: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5ea0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5eb0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5ec0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ed0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5ef0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5f00: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5f30: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f40: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f70: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f80: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5fc0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6000: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6010: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6020: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6030: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6090: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
60a0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
60d0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60e0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6150: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6160: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6190: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
61a0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
61d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61e0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6210: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6220: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6260: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6270: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6280: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6290: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
62b0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
62c0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
62d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6300: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6310: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6320: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6330: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6360: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6380: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6390: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63a0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
63b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
63c0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
63d0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
63e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
63f0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6400: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6410: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6420: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6430: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6440: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6450: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6460: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6470: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6480: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6490: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
64a0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
64b0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
64c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
64d0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
64e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
64f0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6500: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6510: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6520: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6530: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6540: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6550: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6560: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6570: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6580: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6590: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
65a0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
65b0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
65c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
65d0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
65e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
65f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6600: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6610: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6620: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6630: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6640: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6650: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6660: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6670: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6680: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6690: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
66b0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
66c0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
66d0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
66e0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
66f0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6700: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6710: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6720: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6730: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6740: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6750: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6760: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6770: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6780: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6790: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
67a0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
67b0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
67c0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
67d0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
67e0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
67f0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6800: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6810: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6820: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6830: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6840: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6850: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6860: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6870: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6880: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6890: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
68a0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
68b0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
68c0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
68d0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
68e0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
68f0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6900: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6910: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6920: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6930: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6950: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6970: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6980: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6990: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
69a0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6aa0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6ab0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6b10: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6b20: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b80: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6b90: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6bb0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6bc0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bf0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6c00: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6c20: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6c30: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6c50: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6c60: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6c70: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6c80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6c90: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6ca0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6cb0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6cc0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6cd0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6ce0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6cf0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d00: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6d20: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6d30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d40: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6d50: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6d60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6d70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6d80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6d90: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6da0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6db0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6dc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6dd0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6de0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6df0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6e00: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6e10: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6e20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6e30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e40: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6e50: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6e60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6e70: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6e80: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6e90: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ea0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6eb0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6ec0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6ed0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ee0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6ef0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6f00: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6f10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6f20: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6f30: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f40: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6f50: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6f60: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6f70: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6f80: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6f90: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6fa0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6fb0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6fc0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6fd0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6fe0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6ff0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7000: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7010: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7020: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7030: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7040: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7050: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7060: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7070: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7080: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7090: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
70a0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
70b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
70c0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
70d0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
70e0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
70f0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7100: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7110: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7120: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7130: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7140: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7150: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7160: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7170: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7180: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7190: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
71a0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
71b0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
71c0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
71d0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
71e0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
71f0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7200: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7210: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7220: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7230: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7240: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7250: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7260: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7270: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7280: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7290: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
72a0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
72b0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
72c0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
72d0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
72e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7380: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7390: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
73a0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
73b0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
73c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
73d0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
73e0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
73f0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7400: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7410: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7420: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7430: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7440: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7450: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7460: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7470: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7480: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7490: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
74a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
74b0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
74c0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
74d0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
74e0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
74f0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7500: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7510: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7520: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7530: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7540: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7560: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7570: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7580: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7590: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
75a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
75b0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
75c0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
75d0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
75e0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
75f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7600: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7610: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7620: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7630: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7640: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7650: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7660: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7670: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7680: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7690: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
76a0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
76b0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
76c0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
76d0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
76e0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
76f0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7700: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7710: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7720: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7740: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7760: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7770: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7780: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7790: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
77a0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
77b0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
77c0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
77d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77e0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
77f0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7800: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7810: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7820: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7830: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7840: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7850: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7870: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7880: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7890: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
78a0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
78b0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
78c0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
78d0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
78e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
78f0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7900: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7910: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7920: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7930: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7940: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7950: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7960: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7970: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7980: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7990: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
79a0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
79b0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
79c0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
79d0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
79e0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
79f0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7a00: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7a10: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7a20: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7a30: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7a50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a60: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7a70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a80: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7a90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7aa0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7ab0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ac0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7ad0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7ae0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7af0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7b00: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7b10: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7b20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7b30: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b40: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7b50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7b60: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7b70: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7b80: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7b90: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7ba0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7bb0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7bc0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7bd0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7be0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7bf0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7c00: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7c10: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7c20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7c30: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c40: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7c50: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7c60: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7c70: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7c80: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7c90: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7cb0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7cc0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7cd0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7ce0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7cf0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7d00: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7d10: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7d20: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7d30: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d40: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7d50: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7d60: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7d70: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7d80: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7d90: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7da0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7db0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7dc0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7dd0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7de0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7df0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7e00: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7e10: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7e20: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7e30: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e40: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7e50: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7e60: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7e70: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7e80: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7e90: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7ea0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7eb0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7ec0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7ed0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ee0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7ef0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f00: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f10: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f20: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7f30: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f40: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7f50: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7f60: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7f70: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7f80: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7f90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7fa0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7fb0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7fc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7fd0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7fe0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7ff0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8000: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8010: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8020: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8030: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8040: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8050: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8060: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8070: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8080: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8090: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
80a0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
80b0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
80c0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
80d0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
80e0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
80f0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8100: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8110: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8120: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8130: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8140: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8150: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8160: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8170: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8190: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
81c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81d0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
81e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81f0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8200: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8210: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8220: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8230: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8250: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8260: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8270: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8290: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
82a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
82b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
82d0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
82e0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
82f0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8300: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8310: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8320: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8330: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8340: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8350: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8360: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8370: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8380: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8390: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
83a0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
83b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
83c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
83d0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
83e0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
83f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8400: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8410: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8420: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8430: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8440: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8450: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8460: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8480: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8490: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
84a0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
84b0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
84c0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
84d0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
84e0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
84f0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8500: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8510: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8520: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8530: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8540: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8550: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8560: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8570: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8580: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8590: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
85a0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
85b0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
85c0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
85d0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
85e0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
85f0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8600: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8610: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8620: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8630: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8640: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8650: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8660: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8680: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8690: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86a0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
86b0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
86c0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
86d0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
86e0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
86f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8710: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8720: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8730: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8740: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8750: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8760: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8770: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8780: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8790: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
87a0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
87b0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
87c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
87d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
87e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87f0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8800: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8810: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8820: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8830: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8840: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8850: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8860: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8870: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8890: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
88a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
88c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
88d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88e0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
88f0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8910: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8920: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8930: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8940: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8950: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8960: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8970: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8980: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8990: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
89a0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
89b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89c0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
89d0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
89e0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
89f0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a00: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8a30: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a40: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8a50: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8a60: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8a70: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8a80: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8a90: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8aa0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ab0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8ac0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8ad0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8ae0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8af0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b00: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b10: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b20: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8b30: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b40: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8b50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8b60: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8b70: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8b80: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8b90: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8ba0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8bb0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8bc0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8bd0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8be0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8bf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8c00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8c20: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8c30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c40: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8c50: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8c60: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8c70: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8c80: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8c90: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8ca0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8cb0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8cc0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8cd0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ce0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8cf0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8d00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8d10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8d20: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8d30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d40: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8d50: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8d60: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8d70: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8d80: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8d90: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8da0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8db0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8dc0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8dd0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8de0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8df0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8e00: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8e10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8e20: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8e30: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e40: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8e50: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8e60: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8e70: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e80: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e90: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8ea0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8eb0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8ec0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8ed0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ee0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8ef0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8f00: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8f10: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8f20: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8f30: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f40: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8f50: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8f60: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8f70: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f80: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f90: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8fa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8fb0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8fc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8fd0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8ff0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9000: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9010: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9020: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9030: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9040: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9050: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9060: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9070: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9080: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9090: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
90a0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
90b0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
90c0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
90d0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
90e0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
90f0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9100: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9110: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9120: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9130: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9140: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9150: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9160: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9170: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9180: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9190: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
91a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
91b0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
91c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
91d0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
91e0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
91f0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9200: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9210: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9220: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9230: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9240: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9250: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9260: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9270: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9280: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9290: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
92a0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
92b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92c0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
92d0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
92e0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
92f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9300: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9310: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9320: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9330: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9340: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9350: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9360: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9370: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9380: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9390: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
93a0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
93b0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
93c0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
93d0: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
93e0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
93f0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9400: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9410: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9420: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9430: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9440: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9450: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9460: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9470: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9480: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9490: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
94a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
94b0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
94c0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
94d0: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
94e0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
94f0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9500: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9510: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9520: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9530: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9540: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9550: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9560: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9570: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9580: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9590: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
95a0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
95b0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
95c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
95d0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
95e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
95f0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9600: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9610: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9620: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9630: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9640: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9650: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9660: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9670: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9680: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9690: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
96a0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
96b0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
96c0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
96d0: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
96e0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
96f0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9700: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9710: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9720: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9730: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9740: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9750: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9760: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9770: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9780: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9790: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
97a0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
97b0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
97c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
97d0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
97e0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
97f0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9800: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9810: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9820: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9830: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9850: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9860: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9880: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9890: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
98a0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
98b0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
98c0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
98d0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
98e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
98f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9900: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9910: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9920: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9930: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9940: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9950: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9960: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9970: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9980: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9990: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
99a0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
99b0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
99c0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
99d0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
99e0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
99f0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9a00: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9a10: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9a20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9a30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9a40: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9a50: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9a60: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9a70: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a80: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a90: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9aa0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9ab0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9ac0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9ad0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9ae0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9af0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9b00: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9b10: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9b20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9b30: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9b40: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9b50: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9b60: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9b70: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b80: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b90: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9ba0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9bb0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9bc0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9bd0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9be0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9bf0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9c00: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9c10: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9c20: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9c30: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9c40: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9c50: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9c60: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9c70: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c80: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9ca0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9cb0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9cc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9cd0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9ce0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9cf0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9d00: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9d10: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9d20: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9d30: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9d40: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9d50: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9d60: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9d70: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d80: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d90: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9da0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9db0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9dc0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9dd0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9de0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9df0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9e00: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9e10: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9e20: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9e30: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9e40: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9e50: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9e60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9e70: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e80: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e90: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9ea0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9eb0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9ec0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9ed0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ee0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9ef0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9f00: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9f10: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9f20: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9f30: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9f40: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9f50: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9f60: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9f70: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f90: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9fa0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9fb0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9fc0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9fd0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9fe0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9ff0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a000: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a010: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a020: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a030: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a040: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a070: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a080: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a090: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a0a0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a0b0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a0c0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a0d0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a0e0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a0f0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a100: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a110: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a120: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a140: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a150: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a160: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a170: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a180: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a190: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a1a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a1b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a1c0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a1d0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a1e0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a1f0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a200: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a210: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a220: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a230: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a240: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a250: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a260: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a270: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a280: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a290: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a2a0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a2b0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a2d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a2e0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a2f0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a300: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a310: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a320: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a330: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a340: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a350: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a360: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a370: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a380: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a390: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a3a0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a3b0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a3c0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a3d0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a3e0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a3f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a400: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a410: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a420: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a430: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a440: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a450: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a460: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a470: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a480: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a490: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a4a0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a4b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a4c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a4d0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a4e0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a4f0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a500: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a510: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a520: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a530: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a540: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a550: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a560: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a570: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a580: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a590: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a5a0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a5b0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a5c0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a5d0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a5e0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a5f0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a600: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a610: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a620: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a630: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a640: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a650: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a660: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a670: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a680: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a690: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a6a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a6b0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
a6c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a6d0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
a6e0: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
a6f0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
a700: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
a710: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
a720: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
a730: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
a740: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a750: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
a760: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
a770: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
a780: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
a790: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
a7a0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
a7b0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
a7c0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
a7d0: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
a7e0: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
a7f0: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
a800: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
a810: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
a820: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
a830: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
a840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a850: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
a860: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
a870: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
a880: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
a890: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a8a0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
a8b0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
a8c0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
a8d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
a8e0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
a8f0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
a900: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
a910: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
a920: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
a930: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
a940: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a950: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a960: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
a970: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
a980: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
a990: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
a9a0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
a9b0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
a9c0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
a9d0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
a9e0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
a9f0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
aa00: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
aa10: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
aa20: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
aa30: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
aa40: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
aa50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aa60: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aa70: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
aa80: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
aa90: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
aaa0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
aab0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
aac0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
aad0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
aae0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
aaf0: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
ab00: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
ab10: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
ab20: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
ab30: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
ab40: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
ab50: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
ab60: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [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 72 65 74  file control ret
ab90: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
aba0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
abb0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
abc0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
abd0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
abe0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
abf0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ac00: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ac10: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ac20: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ac30: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ac40: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ac50: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ac60: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
ac70: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
ac80: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
ac90: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
aca0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
acb0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
acc0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
acd0: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
ace0: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
acf0: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
ad00: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
ad10: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ad20: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ad30: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
ad40: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
ad50: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
ad60: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
ad70: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
ad80: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
ad90: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
ada0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
adb0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
adc0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
add0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
ade0: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
adf0: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
ae00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ae10: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
ae20: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
ae30: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
ae40: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ae50: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
ae60: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
ae70: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
ae80: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
ae90: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
aea0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
aeb0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
aec0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
aed0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
aee0: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
aef0: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
af00: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
af10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
af20: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
af30: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
af40: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
af50: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
af60: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
af70: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
af80: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
af90: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
afa0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
afb0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
afc0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
afd0: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
afe0: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
aff0: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b000: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b010: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b020: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b030: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b040: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b050: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b060: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b070: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b080: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b090: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b0a0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b0b0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b0c0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b0d0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b0e0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b0f0: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b100: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b110: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b120: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b130: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b140: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b150: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b160: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b170: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b180: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b190: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b1b0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b1c0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b1d0: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b1e0: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b1f0: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b200: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b210: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b220: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b230: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b240: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b250: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b260: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b270: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b280: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b290: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b2a0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b2b0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b2c0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b2d0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b2e0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b2f0: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b300: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b310: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b320: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b330: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b340: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b360: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b370: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b380: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b390: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b3a0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b3b0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b3c0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b3d0: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b3e0: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b3f0: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b400: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b410: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b420: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b430: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b440: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b450: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b460: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b470: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b480: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b490: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b4a0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b4b0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b4c0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b4d0: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b4e0: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b4f0: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b500: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b510: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b520: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b530: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b540: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b550: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b560: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b570: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b580: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b590: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b5a0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b5b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b5c0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b5d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b5e0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b5f0: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b600: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b610: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b620: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b630: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b640: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b650: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b660: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b670: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b680: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b690: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b6a0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b6b0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b6c0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b6d0: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b6e0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b6f0: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b700: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b710: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b720: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b730: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b740: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b750: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b760: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b770: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b780: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b790: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b7a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b7b0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b7c0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
b7d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
b7e0: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
b7f0: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
b800: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
b810: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
b820: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
b830: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
b840: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
b850: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
b860: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
b870: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
b880: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b890: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b8a0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b8b0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b8c0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
b8d0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b8e0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b8f0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b900: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b910: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
b920: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
b930: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
b940: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
b950: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
b960: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
b970: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
b980: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
b990: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
b9a0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
b9b0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
b9c0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
b9d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b9e0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
b9f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ba00: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
ba10: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
ba20: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
ba30: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
ba40: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
ba50: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
ba60: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
ba70: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
ba80: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
ba90: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
baa0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
bab0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
bac0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
bad0: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
bae0: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
baf0: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
bb00: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
bb10: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
bb20: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
bb30: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
bb40: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
bb50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bb60: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
bb70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
bb80: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
bb90: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
bba0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
bbb0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
bbc0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
bbd0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
bbe0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
bbf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bc00: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
bc10: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bc20: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
bc30: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
bc40: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
bc50: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
bc60: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bc70: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
bc80: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bc90: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bca0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bcb0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bcc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bcd0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bce0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bcf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bd00: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bd10: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bd20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bd30: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bd40: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bd50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd60: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bd70: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bd80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd90: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bda0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bdb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bdc0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
bdd0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
bde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
bdf0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
be00: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
be10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
be20: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
be30: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
be40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
be50: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
be60: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
be80: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
be90: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
bea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
beb0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
bec0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
bed0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
bee0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
bef0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
bf00: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
bf10: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
bf20: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
bf30: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
bf40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bf50: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bf60: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
bf70: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
bf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf90: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
bfa0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bfb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bfc0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bfd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
bfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bff0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
c000: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
c010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c020: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
c030: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
c040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c050: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
c060: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
c070: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c080: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
c090: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
c0a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c0b0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
c0c0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
c0d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c0e0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
c0f0: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
c100: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c110: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c120: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c150: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53      26.#define S
c160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
c170: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c180: 20 20 20 32 37 0a 0a 2f 2a 20 64 65 70 72 65 63     27../* deprec
c190: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
c1a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
c1b0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c1c0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c1d0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c1e0: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
c1f0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
c200: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
c210: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
c220: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
c230: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
c240: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
c250: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
c260: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
c270: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
c280: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
c290: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
c2a0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
c2b0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
c2c0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
c2d0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
c2e0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
c2f0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
c300: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
c310: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
c320: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
c330: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
c340: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
c350: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
c360: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
c370: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
c380: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
c390: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
c3a0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
c3b0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
c3c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
c3d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
c3e0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
c3f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
c400: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
c410: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
c420: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
c430: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
c440: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
c450: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
c460: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
c470: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
c480: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
c490: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
c4a0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
c4b0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
c4c0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
c4d0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
c4e0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
c4f0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
c500: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
c510: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
c520: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
c530: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
c540: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
c550: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
c560: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
c570: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
c580: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
c590: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
c5a0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
c5b0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
c5c0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
c5d0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
c5e0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
c5f0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
c600: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c610: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
c620: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
c630: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
c640: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
c650: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
c660: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
c670: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
c680: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
c690: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
c6a0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
c6b0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
c6c0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
c6d0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
c6e0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
c6f0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
c700: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
c710: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
c720: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
c730: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
c740: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
c750: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
c760: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
c770: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
c780: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
c790: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c7a0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
c7b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
c7c0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
c7d0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
c7e0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
c7f0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
c800: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
c810: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
c820: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
c830: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
c840: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
c850: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
c860: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
c870: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
c880: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
c890: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
c8a0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
c8b0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
c8c0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
c8d0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
c8e0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
c8f0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
c900: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
c910: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
c920: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c930: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c940: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c950: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c960: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c970: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c980: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c990: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c9a0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c9b0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c9c0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c9d0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c9e0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c9f0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
ca00: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
ca10: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
ca20: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
ca30: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
ca40: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
ca50: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
ca60: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ca70: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ca80: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
ca90: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
caa0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
cab0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
cac0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
cad0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
cae0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
caf0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
cb00: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
cb10: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
cb20: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
cb30: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
cb40: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
cb50: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
cb60: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
cb70: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
cb80: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
cb90: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
cba0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
cbb0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
cbc0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
cbd0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
cbe0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
cbf0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
cc00: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
cc10: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
cc20: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
cc30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
cc40: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
cc50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
cc60: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
cc70: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
cc80: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
cc90: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
cca0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
ccb0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
ccc0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
ccd0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
cce0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
ccf0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
cd00: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
cd10: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
cd20: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
cd30: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
cd40: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
cd50: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
cd60: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
cd70: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
cd80: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
cd90: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cda0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
cdb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
cdc0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
cdd0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
cde0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
cdf0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
ce00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
ce10: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
ce20: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
ce30: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
ce40: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
ce50: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
ce60: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
ce70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
ce80: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
ce90: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
cea0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
ceb0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
cec0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
ced0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
cee0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
cef0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
cf00: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
cf10: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
cf20: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
cf30: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
cf40: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
cf50: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
cf60: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
cf70: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
cf80: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
cf90: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
cfa0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
cfb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
cfc0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
cfd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
cfe0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
cff0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d000: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
d010: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d020: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
d030: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d040: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
d050: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
d060: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
d070: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
d080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
d090: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
d0a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d0b0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
d0c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
d0d0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
d0e0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
d0f0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
d100: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
d110: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
d120: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
d130: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
d140: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
d150: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
d160: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
d170: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
d180: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
d190: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
d1a0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
d1b0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
d1c0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
d1d0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
d1e0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
d1f0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
d200: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
d210: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
d220: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
d230: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
d240: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
d250: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
d260: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
d270: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
d280: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
d290: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
d2a0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
d2b0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
d2c0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
d2d0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
d2e0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
d2f0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
d300: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
d310: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
d320: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d330: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
d340: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
d360: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
d370: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
d380: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
d390: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
d3a0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
d3b0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
d3c0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
d3d0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
d3e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d3f0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
d400: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
d410: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
d420: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
d430: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
d440: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
d450: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
d460: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
d470: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
d480: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
d490: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
d4a0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
d4b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d4c0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
d4d0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
d4e0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
d4f0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
d500: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
d510: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
d520: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
d530: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
d540: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
d550: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
d560: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
d570: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
d580: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
d590: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
d5a0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
d5b0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
d5c0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
d5d0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
d5e0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
d5f0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
d600: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
d610: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
d620: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
d630: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
d640: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
d650: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
d660: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
d670: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
d680: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
d690: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
d6a0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
d6b0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
d6c0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
d6d0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d6e0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
d6f0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
d700: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
d710: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
d720: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
d730: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
d740: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
d750: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
d760: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
d770: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
d780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
d790: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
d7a0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
d7b0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
d7c0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
d7d0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
d7e0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
d7f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d800: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
d810: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
d820: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
d830: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
d840: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
d850: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
d860: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
d870: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
d880: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
d890: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d8a0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
d8b0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
d8c0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
d8d0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
d8e0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
d8f0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d900: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
d910: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
d920: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d930: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d940: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d950: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d960: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d970: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d980: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d990: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d9a0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d9b0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d9c0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d9d0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d9e0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d9f0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
da00: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
da10: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
da20: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
da30: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
da40: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
da50: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
da60: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
da70: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
da80: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
da90: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
daa0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
dab0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
dac0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
dad0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
dae0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
daf0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
db00: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
db10: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
db20: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
db30: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
db40: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
db50: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
db60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
db70: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
db80: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
db90: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
dba0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
dbb0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
dbc0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
dbd0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
dbe0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
dbf0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
dc00: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
dc10: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
dc20: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
dc30: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
dc40: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
dc50: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
dc60: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
dc70: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
dc80: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
dc90: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
dca0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
dcb0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
dcc0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
dcd0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
dce0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
dcf0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
dd00: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
dd10: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
dd20: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
dd30: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
dd40: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
dd50: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
dd60: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
dd70: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
dd80: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
dd90: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
dda0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
ddb0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
ddc0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
ddd0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
dde0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
ddf0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
de00: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
de10: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
de20: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
de30: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
de40: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
de50: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
de60: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
de70: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
de80: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
de90: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
dea0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
deb0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
dec0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
ded0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
dee0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
def0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
df00: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
df10: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
df20: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
df30: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
df40: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
df50: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
df60: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
df70: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
df80: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
df90: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
dfa0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
dfb0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
dfc0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
dfd0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
dfe0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
dff0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
e000: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
e010: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
e020: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
e030: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
e040: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
e050: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
e060: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
e070: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
e080: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
e090: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
e0a0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
e0b0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
e0c0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
e0d0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
e0e0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
e0f0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
e100: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
e110: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
e120: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
e130: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
e140: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
e150: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
e160: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
e170: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
e180: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
e190: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
e1a0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
e1b0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
e1c0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
e1d0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
e1e0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
e1f0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
e200: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
e210: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
e220: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
e230: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
e240: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
e250: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
e260: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
e270: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
e280: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
e290: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
e2a0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
e2b0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
e2c0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
e2d0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
e2e0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
e2f0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
e300: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
e310: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
e320: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
e330: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
e340: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
e350: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
e360: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
e370: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
e380: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
e390: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
e3a0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
e3b0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
e3c0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
e3d0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
e3e0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
e3f0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
e400: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
e410: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
e420: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
e430: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
e440: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
e450: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
e460: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
e470: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
e480: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
e490: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e4a0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e4b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
e4c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
e4d0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
e4e0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
e4f0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
e500: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e510: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e520: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
e530: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
e540: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e550: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
e560: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
e570: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
e580: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
e590: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e5a0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
e5b0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
e5c0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
e5d0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
e5e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e5f0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
e600: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
e610: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e620: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
e630: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
e640: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
e650: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
e660: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
e670: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
e680: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
e690: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
e6a0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
e6b0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
e6c0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
e6d0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
e6e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
e6f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e700: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
e710: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
e720: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
e730: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
e740: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
e750: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
e760: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
e770: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e780: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e790: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
e7a0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e7b0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
e7c0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
e7d0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
e7e0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
e7f0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
e800: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
e810: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
e820: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
e830: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
e840: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e850: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e860: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
e870: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e880: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
e890: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
e8a0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
e8b0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
e8c0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
e8d0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e8e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e8f0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
e900: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
e910: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e920: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e930: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e940: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e950: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e960: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e970: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e980: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e990: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e9a0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e9b0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e9c0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e9d0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e9e0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e9f0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
ea00: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
ea10: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
ea20: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
ea30: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
ea40: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
ea50: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
ea60: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
ea70: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
ea80: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
ea90: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
eaa0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
eab0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
eac0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
ead0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
eae0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
eaf0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
eb00: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
eb10: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
eb20: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
eb30: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
eb40: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
eb50: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
eb60: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
eb70: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
eb80: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
eb90: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
eba0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
ebb0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
ebc0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
ebd0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
ebe0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
ebf0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
ec00: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
ec10: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
ec20: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
ec30: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
ec40: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
ec50: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
ec60: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
ec70: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
ec80: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
ec90: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
eca0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
ecb0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
ecc0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
ecd0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
ece0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
ecf0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
ed00: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
ed10: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
ed20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
ed30: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
ed40: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
ed50: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
ed60: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
ed70: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
ed80: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
ed90: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
eda0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
edb0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
edc0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
edd0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
ede0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
edf0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
ee00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
ee10: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
ee20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
ee30: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
ee40: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
ee50: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
ee60: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
ee70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
ee80: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
ee90: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
eea0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
eeb0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
eec0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
eed0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
eee0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
eef0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
ef00: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
ef10: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
ef20: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
ef30: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
ef40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
ef50: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
ef60: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
ef70: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
ef80: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
ef90: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
efa0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
efb0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
efc0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
efd0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
efe0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
eff0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
f000: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f010: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f020: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f030: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f040: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f050: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f060: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f070: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
f080: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
f090: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
f0a0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
f0b0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
f0c0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
f0d0: 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
f0e0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
f0f0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
f100: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
f110: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
f120: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
f130: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
f140: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
f150: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
f160: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
f170: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
f180: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
f190: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f1a0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
f1b0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
f1c0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
f1d0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
f1e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f1f0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
f200: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
f210: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
f220: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
f230: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
f240: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
f250: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
f260: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
f270: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
f280: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
f290: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
f2a0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
f2b0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
f2c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
f2d0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
f2e0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
f2f0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
f300: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
f310: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
f320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
f330: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
f340: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
f350: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
f360: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
f370: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
f380: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f390: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
f3a0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
f3b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
f3c0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f3d0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
f3e0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
f3f0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
f400: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
f410: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f420: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
f430: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
f440: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
f450: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
f460: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
f470: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
f480: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
f490: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
f4a0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
f4b0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
f4c0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
f4d0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
f4e0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
f4f0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
f500: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f510: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
f520: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
f530: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
f540: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
f550: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
f560: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
f570: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
f580: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
f590: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f5a0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
f5b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
f5c0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
f5d0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
f5e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f5f0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
f600: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
f610: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
f620: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
f630: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
f640: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
f650: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
f660: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
f670: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
f680: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f690: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f6a0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
f6b0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
f6c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f6d0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
f6e0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
f6f0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
f700: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
f710: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
f720: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f730: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
f740: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
f750: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
f760: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
f770: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
f780: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
f790: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f7a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f7b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
f7c0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
f7d0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f7e0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
f7f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f800: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
f810: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
f820: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
f830: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
f840: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
f850: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
f860: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
f870: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
f880: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
f890: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
f8a0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
f8b0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
f8c0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
f8d0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
f8e0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
f8f0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
f900: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f910: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
f920: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f930: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f940: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f950: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f960: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f970: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f980: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f990: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f9a0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f9b0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f9c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f9d0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f9e0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f9f0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
fa00: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
fa10: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
fa20: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
fa30: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
fa40: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
fa50: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
fa60: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
fa70: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
fa80: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fa90: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
faa0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
fab0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
fac0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fad0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
fae0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
faf0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
fb00: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
fb10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fb20: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
fb30: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
fb40: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
fb50: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
fb60: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
fb70: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
fb80: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
fb90: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
fba0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
fbb0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
fbc0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
fbd0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
fbe0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
fbf0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
fc00: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
fc10: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
fc20: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
fc30: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
fc40: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
fc50: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
fc60: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
fc70: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
fc80: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
fc90: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
fca0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
fcb0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
fcc0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
fcd0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
fce0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
fcf0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
fd00: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
fd10: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
fd20: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
fd30: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
fd40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fd50: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
fd60: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
fd70: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
fd80: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
fd90: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
fda0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
fdb0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
fdc0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
fdd0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
fde0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
fdf0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
fe00: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
fe10: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
fe20: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
fe30: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
fe40: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
fe50: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
fe60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fe70: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
fe80: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
fe90: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
fea0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
feb0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
fec0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
fed0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
fee0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
fef0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
ff00: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
ff10: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
ff20: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
ff30: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
ff40: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
ff50: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
ff60: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
ff70: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
ff80: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
ff90: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
ffa0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
ffb0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
ffc0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
ffd0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
ffe0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
fff0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
10000 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10010 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
10020 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
10030 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
10040 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
10050 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
10060 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
10070 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
10080 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10090 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
100a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
100b0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
100c0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
100d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
100e0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
100f0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
10100 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
10110 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10120 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
10130 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
10140 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
10150 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
10160 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
10170 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
10180 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
10190 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
101a0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
101b0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
101c0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
101d0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
101e0 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
101f0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
10200 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
10210 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
10220 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
10230 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
10240 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
10250 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
10260 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
10270 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
10280 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
10290 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
102a0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
102b0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
102c0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
102d0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
102e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
102f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10300 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
10310 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
10320 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
10330 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
10340 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
10350 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
10360 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
10370 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10380 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
10390 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
103a0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
103b0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
103c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
103d0 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
103e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
103f0 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
10400 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
10410 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10420 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10430 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
10440 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
10450 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10460 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
10470 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
10480 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
10490 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
104a0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
104b0 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
104c0 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
104d0 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
104e0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
104f0 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
10500 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
10510 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
10520 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
10530 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
10540 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
10550 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
10560 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73  ..**.** <b>The s
10570 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10580 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
10590 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65   threadsafe. The
105a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
105b0 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
105c0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
105d0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
105e0 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
105f0 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10600 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10610 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f  () is running.</
10620 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  b>.**.** The sql
10630 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10640 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f  terface.** may o
10650 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
10660 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
10670 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
10680 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
10690 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
106a0 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
106b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
106c0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
106d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
106e0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
106f0 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
10700 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
10710 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
10720 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
10730 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
10740 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
10750 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
10760 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
10770 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
10780 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
10790 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
107a0 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
107b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
107c0 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
107d0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
107e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
107f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
10800 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
10810 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
10820 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
10830 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
10840 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
10850 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
10860 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
10870 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10880 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
10890 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
108a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
108b0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
108c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
108d0 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
108e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
108f0 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
10900 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
10910 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
10920 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
10930 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
10940 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
10950 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
10960 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
10970 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
10980 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
10990 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
109a0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
109b0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
109c0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
109d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
109e0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
109f0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
10a00 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
10a10 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10a20 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
10a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
10a40 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
10a50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10a60 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
10a70 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
10a80 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10a90 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
10aa0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
10ab0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
10ac0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
10ad0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
10ae0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
10af0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
10b00 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
10b10 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10b20 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
10b30 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
10b40 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
10b50 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
10b60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10b70 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
10b80 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
10b90 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
10ba0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
10bb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10bc0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
10bd0 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
10be0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
10bf0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10c00 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
10c10 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
10c20 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
10c30 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
10c40 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
10c50 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
10c60 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
10c70 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
10c80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10c90 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
10ca0 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
10cb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10cc0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
10cd0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
10ce0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
10cf0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
10d00 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
10d10 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
10d20 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
10d30 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
10d40 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
10d50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
10d60 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
10d70 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
10d80 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
10d90 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
10da0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
10db0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
10dc0 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
10dd0 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
10de0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
10df0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
10e00 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
10e10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10e20 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
10e30 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
10e40 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
10e50 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
10e60 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
10e70 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
10e80 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
10e90 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
10ea0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
10eb0 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
10ec0 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
10ed0 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
10ee0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
10ef0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10f00 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
10f10 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
10f20 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
10f30 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
10f40 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
10f50 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
10f60 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
10f70 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
10f80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
10f90 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
10fa0 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
10fb0 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
10fc0 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
10fd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
10fe0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
10ff0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
11000 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
11010 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
11020 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
11030 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
11040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11050 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
11060 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
11070 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
11080 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
11090 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
110a0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
110b0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
110c0 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
110d0 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
110e0 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
110f0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
11100 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
11110 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
11120 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
11130 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
11140 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
11150 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
11160 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
11170 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
11180 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
11190 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
111a0 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
111b0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
111c0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
111d0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
111e0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
111f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
11200 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
11210 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
11220 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
11230 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
11240 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
11250 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
11260 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
11270 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
11280 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
11290 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
112a0 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
112b0 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
112c0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
112d0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
112e0 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
112f0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
11300 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
11310 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
11320 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
11330 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
11340 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
11350 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
11360 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
11370 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
11380 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
11390 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
113a0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
113b0 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
113c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
113d0 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
113e0 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
113f0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
11400 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
11410 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
11420 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
11430 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
11440 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11450 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
11460 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
11470 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
11480 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
11490 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
114a0 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
114b0 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
114c0 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
114d0 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
114e0 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
114f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
11500 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
11510 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
11520 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
11530 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
11540 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
11550 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
11560 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
11570 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
11580 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
11590 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
115a0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
115b0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
115c0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
115d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
115e0 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
115f0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
11600 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
11610 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
11620 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
11630 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
11640 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
11650 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
11660 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
11670 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
11680 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11690 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
116a0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
116b0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
116c0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
116d0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
116e0 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
116f0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
11700 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
11710 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
11720 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
11730 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
11740 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
11750 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
11760 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
11770 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
11780 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
11790 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
117a0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
117b0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
117c0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
117d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
117e0 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
117f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
11800 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
11810 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
11820 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
11830 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
11840 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
11850 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
11860 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
11870 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
11880 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
11890 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
118a0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
118b0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
118c0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
118d0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
118e0 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
118f0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11900 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
11910 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
11920 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
11930 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
11940 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
11950 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
11960 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11970 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
11980 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11990 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
119a0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
119b0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
119c0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
119d0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
119e0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
119f0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
11a00 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
11a10 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
11a20 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
11a30 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
11a40 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
11a50 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
11a60 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11a70 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
11a80 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11a90 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
11aa0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
11ab0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
11ac0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
11ad0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
11ae0 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
11af0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
11b00 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
11b10 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
11b20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
11b30 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
11b40 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11b50 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
11b60 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
11b70 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
11b80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11b90 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
11ba0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
11bb0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
11bc0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
11bd0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
11be0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
11bf0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
11c00 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
11c10 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
11c20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
11c30 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
11c40 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
11c50 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
11c60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11c70 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
11c80 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
11c90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11ca0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
11cb0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11cc0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
11cd0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11ce0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
11cf0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
11d00 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
11d10 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
11d20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11d30 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
11d40 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
11d50 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
11d60 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
11d70 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
11d80 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
11d90 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
11da0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
11db0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
11dc0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
11dd0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
11de0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
11df0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
11e00 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
11e10 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
11e20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11e30 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
11e40 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
11e50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11e60 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
11e70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11e80 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
11e90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11ea0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
11eb0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11ec0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
11ed0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
11ee0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
11ef0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
11f00 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11f10 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
11f20 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
11f30 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
11f40 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
11f50 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
11f60 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
11f70 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
11f80 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11f90 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11fa0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11fb0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11fc0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11fd0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11fe0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11ff0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
12000 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
12010 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
12020 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
12030 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
12040 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
12050 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12060 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
12070 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
12080 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
12090 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
120a0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
120b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
120c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
120d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
120e0 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
120f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12100 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
12110 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12120 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12130 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12140 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12150 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12160 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
12170 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
12180 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
12190 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
121a0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
121b0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
121c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
121d0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
121e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
121f0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
12200 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
12210 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
12220 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
12230 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12240 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
12250 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
12260 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
12270 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
12280 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
12290 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
122a0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
122b0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
122c0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
122d0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
122e0 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
122f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12300 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12310 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12320 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12330 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12340 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12350 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12360 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12370 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
12380 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
12390 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
123a0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
123b0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
123c0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
123d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
123e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
123f0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12400 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12410 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
12420 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12430 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12450 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
12460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12470 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
12480 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12490 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
124a0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
124b0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
124c0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
124d0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
124e0 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
124f0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
12500 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
12510 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
12520 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
12530 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
12540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12550 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
12560 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12570 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
12580 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
12590 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
125a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
125b0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
125c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
125d0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
125e0 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
125f0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
12600 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
12610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
12620 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12630 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
12640 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
12650 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
12660 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
12670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12680 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
12690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
126a0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
126b0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
126c0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
126d0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
126e0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
126f0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12700 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12710 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12720 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12730 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12740 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12750 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
12760 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12770 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12780 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12790 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
127a0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
127b0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
127c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
127d0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
127e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
127f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12800 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
12810 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12820 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
12830 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
12840 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12850 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12860 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12870 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
12880 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12890 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
128a0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
128b0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
128c0 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
128d0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
128e0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
128f0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12900 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
12910 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
12920 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
12930 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12940 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12950 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
12960 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
12970 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
12980 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
12990 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
129a0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
129b0 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
129c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
129d0 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
129e0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
129f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12a00 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
12a10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12a20 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
12a30 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12a40 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12a50 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
12a60 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12a70 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
12a80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12a90 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12aa0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12ab0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12ac0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
12ad0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
12ae0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
12af0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
12b00 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
12b10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12b20 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
12b30 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
12b40 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
12b50 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
12b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12b70 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12b80 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
12b90 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
12ba0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12bb0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
12bc0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
12bd0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
12be0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12c00 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
12c10 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
12c20 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
12c30 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
12c40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
12c50 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
12c60 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
12c70 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
12c80 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
12c90 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
12ca0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
12cb0 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
12cc0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12cd0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12ce0 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
12cf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12d00 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
12d10 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
12d20 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
12d30 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
12d40 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
12d50 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
12d60 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
12d70 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
12d80 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
12d90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
12da0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12db0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
12dc0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
12dd0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
12de0 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tus64()].**   </
12df0 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
12e00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
12e10 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
12e20 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
12e30 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
12e40 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
12e50 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
12e60 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
12e70 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
12e80 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
12e90 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
12ea0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
12eb0 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
12ec0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12ed0 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
12ee0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
12ef0 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
12f00 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
12f10 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f  CONFIG_SCRATCH o
12f20 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
12f30 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
12f40 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53  buffer.** that S
12f50 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
12f60 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  r scratch memory
12f70 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74  .  ^(There are t
12f80 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a  hree arguments.*
12f90 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  * to SQLITE_CONF
12fa0 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70  IG_SCRATCH:  A p
12fb0 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
12fc0 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
12fd0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
12fe0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
12ff0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
13000 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
13010 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
13020 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13030 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
13040 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
13050 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
13060 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e  locations (N).)^
13070 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
13080 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
13090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
130a0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
130b0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
130c0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
130d0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
130e0 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73  Lite will not us
130f0 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  e more than one 
13100 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
13110 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e  per thread..** ^
13120 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
13130 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61  r request a scra
13140 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
13150 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
13160 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
13170 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a  base page size..
13180 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  ** ^If SQLite ne
13190 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
131a0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
131b0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
131c0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
131d0 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
131e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
131f0 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
13200 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
13210 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
13220 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
13230 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74  d.<p>.** ^When t
13240 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70  he application p
13250 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75  rovides any amou
13260 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65  nt of scratch me
13270 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51  mory using.** SQ
13280 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13290 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69  TCH, SQLite avoi
132a0 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c  ds unnecessary l
132b0 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  arge.** [sqlite3
132c0 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c  _malloc|heap all
132d0 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  ocations]..** Th
132e0 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62  is can help [Rob
132f0 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e  son proof|preven
13300 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
13310 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75  ion failures] du
13320 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61  e to heap.** fra
13330 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f  gmentation in lo
13340 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65  w-memory embedde
13350 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f  d systems..** </
13360 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13370 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13380 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
13390 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
133a0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
133b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
133c0 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69  G_PAGECACHE opti
133d0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d  on specifies a m
133e0 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68  emory pool.** th
133f0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
13400 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  e for the databa
13410 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
13420 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
13430 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13440 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
13450 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
13460 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61  tion option is a
13470 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70   no-op if an app
13480 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
13490 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
134a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
134b0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
134c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
134d0 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68  PCACHE2]..** ^Th
134e0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
134f0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13500 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13510 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
13520 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
13530 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29  ed memory (pMem)
13540 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13550 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69  ch page cache li
13560 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  ne (sz),.** and 
13570 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61  the number of ca
13580 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a  che lines (N)..*
13590 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
135a0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
135b0 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
135c0 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
135d0 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
135e0 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
135f0 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73   and 65536) plus
13600 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65   some extra byte
13610 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  s for each.** pa
13620 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
13630 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
13640 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79   bytes needed by
13650 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72   the page header
13660 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
13670 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c  mined using [SQL
13680 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13690 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74  E_HDRSZ]..** ^It
136a0 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
136b0 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
136c0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66  ted memory,.** f
136d0 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65  or the sz parame
136e0 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72  ter to be larger
136f0 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e   than necessary.
13700 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72    The pMem.** ar
13710 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65  gument must be e
13720 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
13730 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65  nter or a pointe
13740 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  r to an 8-byte.*
13750 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  * aligned block 
13760 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  of memory of at 
13770 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
13780 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73  , otherwise.** s
13790 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
137a0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
137b0 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69  .** ^When pMem i
137c0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
137d0 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74  te will strive t
137e0 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  o use the memory
137f0 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20   provided.** to 
13800 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63  satisfy page cac
13810 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e  he needs, fallin
13820 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74  g back to [sqlit
13830 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a  e3_malloc()] if.
13840 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20  ** a page cache 
13850 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74  line is larger t
13860 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20  han sz bytes or 
13870 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d  if all of the pM
13880 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  em buffer.** is 
13890 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49  exhausted..** ^I
138a0 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61  f pMem is NULL a
138b0 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  nd N is non-zero
138c0 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61  , then each data
138d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
138e0 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69  ** does an initi
138f0 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69  al bulk allocati
13900 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  on for page cach
13910 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d  e memory.** from
13920 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13930 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66  ()] sufficient f
13940 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73  or N cache lines
13950 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
13960 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34  e or.** of -1024
13970 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73  *N bytes if N is
13980 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66   negative, . ^If
13990 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
139a0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
139b0 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
139c0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
139d0 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61  ed by the initia
139e0 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  l.** allocation,
139f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
13a00 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
13a10 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65  lloc()] separate
13a20 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61  ly for each.** a
13a30 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20  dditional cache 
13a40 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  line. </dd>.**.*
13a50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13a60 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
13a70 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
13a80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13aa0 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63  HEAP option spec
13ab0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
13ac0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a  emory buffer .**
13ad0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
13ae0 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  l use for all of
13af0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
13b00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
13b10 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74  eeds.** beyond t
13b20 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f  hose provided fo
13b30 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
13b40 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
13b50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
13b60 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
13b70 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
13b80 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
13b90 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
13ba0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
13bb0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
13bc0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
13bd0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
13be0 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
13bf0 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
13c00 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
13c10 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
13c20 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
13c30 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13c40 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13c50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13c60 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
13c70 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
13c80 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
13c90 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
13ca0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
13cb0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
13cc0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13cd0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
13ce0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
13cf0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
13d00 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
13d10 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
13d20 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
13d30 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
13d40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13d50 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
13d60 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
13d70 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
13d80 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
13d90 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
13da0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13db0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
13dc0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
13dd0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
13de0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
13df0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
13e00 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
13e10 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
13e20 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
13e30 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
13e40 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
13e50 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13e60 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
13e70 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
13e80 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
13e90 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
13ea0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
13eb0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
13ec0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
13ed0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13ee0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
13ef0 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
13f00 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
13f10 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
13f20 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
13f30 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
13f40 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
13f50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13f60 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
13f70 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13f80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13f90 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13fa0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
13fb0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13fc0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13fd0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
13fe0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13ff0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
14000 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
14010 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
14020 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
14030 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
14040 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
14050 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
14060 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
14070 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
14080 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
14090 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
140a0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
140b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
140c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
140d0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
140e0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
140f0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
14100 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
14110 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
14120 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14130 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14140 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14150 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14160 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14170 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14180 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14190 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
141a0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
141b0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
141c0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
141d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
141e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
141f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
14200 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14210 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
14220 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
14230 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
14240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14250 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
14260 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14270 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
14280 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14290 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
142a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
142b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
142c0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
142d0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
142e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
142f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14300 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
14310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
14320 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
14330 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14340 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14350 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
14360 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
14370 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14380 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
14390 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
143a0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
143b0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
143c0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
143d0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
143e0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
143f0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
14400 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
14410 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
14420 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14430 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14440 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14450 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14460 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14470 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14480 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
14490 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
144a0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
144b0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
144c0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
144d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
144e0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
144f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14500 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
14510 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
14520 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
14530 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
14540 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14550 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14560 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
14570 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14580 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
14590 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
145a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
145b0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
145c0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
145d0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
145e0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
145f0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
14600 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
14610 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
14620 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14630 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
14640 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
14650 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
14660 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
14670 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
14680 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
14690 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
146a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
146b0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
146c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
146d0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
146e0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
146f0 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
14700 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14710 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
14720 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
14730 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
14740 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
14750 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
14760 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14770 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
14780 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
14790 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
147a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
147b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
147c0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
147d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
147e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
147f0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14800 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14810 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14820 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14830 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
14840 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14850 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
14860 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
14870 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
14880 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
14890 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
148a0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
148b0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
148c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
148d0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
148e0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
148f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14900 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
14910 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14920 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
14930 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14950 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14960 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14970 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
14980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14990 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
149a0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
149b0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
149c0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
149d0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
149e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
149f0 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
14a00 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14a10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
14a20 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
14a30 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
14a40 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
14a50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14a60 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
14a70 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
14a80 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
14a90 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
14aa0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14ab0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
14ac0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
14ad0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
14ae0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
14af0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
14b00 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
14b10 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
14b20 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
14b30 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
14b40 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
14b50 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
14b60 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
14b70 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
14b80 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
14b90 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
14ba0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
14bb0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
14bc0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
14bd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
14be0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
14bf0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
14c00 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
14c10 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
14c20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14c30 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
14c40 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
14c50 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
14c60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14c70 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
14c80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14c90 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
14ca0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
14cb0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
14cc0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
14cd0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
14ce0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14cf0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
14d00 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14d10 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
14d20 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
14d30 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
14d40 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
14d50 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
14d60 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
14d70 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
14d80 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
14d90 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
14da0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
14db0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
14dc0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
14dd0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
14de0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
14df0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
14e00 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
14e10 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
14e20 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
14e30 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
14e40 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
14e50 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
14e60 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
14e70 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
14e80 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
14e90 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
14ea0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14eb0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14ec0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14ed0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
14ee0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
14f00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14f10 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
14f20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14f30 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
14f40 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14f50 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
14f60 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
14f70 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
14f80 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
14f90 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
14fa0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
14fb0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
14fc0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14fd0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
14fe0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
14ff0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
15000 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
15010 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
15020 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
15030 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
15040 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
15050 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
15060 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
15070 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
15080 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
15090 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
150a0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
150b0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
150c0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
150d0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
150e0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
150f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
15100 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
15110 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
15120 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
15130 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
15140 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
15150 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
15160 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
15170 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
15180 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
15190 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
151a0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
151b0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
151c0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
151d0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
151e0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
151f0 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
15200 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
15210 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
15220 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
15230 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
15240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15250 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15260 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15270 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
15280 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
15290 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
152a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
152b0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
152c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
152d0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
152e0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
152f0 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
15300 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
15310 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
15320 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
15330 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15340 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15350 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
15360 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
15370 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
15380 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
15390 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
153a0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
153b0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
153c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
153d0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
153e0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
153f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
15400 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
15410 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
15420 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
15430 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15440 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15450 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
15460 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
15470 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
15480 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
15490 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
154a0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
154b0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
154c0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
154d0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
154e0 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
154f0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
15500 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
15510 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
15520 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
15530 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
15540 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
15550 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
15560 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
15570 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
15580 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
15590 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
155a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
155b0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
155c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
155d0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
155e0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
155f0 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
15600 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
15610 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
15620 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
15630 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
15640 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
15650 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
15660 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15670 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15680 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
15690 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
156a0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
156b0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
156c0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
156d0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
156e0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
156f0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
15700 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
15710 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
15720 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15730 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
15740 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15750 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
15760 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
15770 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
15780 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
15790 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
157a0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
157b0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
157c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
157d0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
157e0 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
157f0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
15800 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
15810 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
15820 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15830 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
15840 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15850 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
15860 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15870 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
15880 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15890 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
158a0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
158b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
158c0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
158d0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
158e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
158f0 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
15900 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
15910 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15920 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
15930 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
15940 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
15950 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
15960 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
15970 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
15980 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
15990 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
159a0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
159b0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
159c0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
159d0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
159e0 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
159f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15a00 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
15a10 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
15a20 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
15a30 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
15a40 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
15a50 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
15a60 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
15a70 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
15a80 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
15a90 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
15aa0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
15ab0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15ac0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
15ad0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15ae0 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
15af0 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
15b00 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
15b10 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
15b20 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
15b30 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
15b40 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
15b50 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
15b60 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
15b70 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
15b80 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
15b90 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
15ba0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
15bb0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
15bc0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
15bd0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
15be0 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
15bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15c00 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
15c10 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
15c20 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
15c30 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
15c40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
15c50 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
15c60 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
15c70 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
15c80 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
15c90 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
15ca0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
15cb0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
15cc0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
15cd0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
15ce0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
15cf0 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
15d00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15d10 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
15d20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15d30 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
15d40 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
15d50 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
15d60 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
15d70 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
15d80 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
15d90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
15da0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
15db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15dc0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
15dd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15de0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15df0 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
15e00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15e10 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
15e20 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15e30 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
15e40 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
15e50 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
15e60 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
15e70 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
15e80 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
15e90 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
15ea0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15eb0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
15ec0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
15ed0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
15ee0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
15ef0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
15f00 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
15f10 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
15f20 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15f30 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
15f40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15f50 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
15f60 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15f70 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
15f80 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
15f90 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
15fa0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
15fb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15fc0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
15fd0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
15fe0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
15ff0 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
16000 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
16010 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
16020 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
16030 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
16040 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
16050 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
16060 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
16070 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
16080 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
16090 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
160a0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
160b0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
160c0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
160d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
160e0 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
160f0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16100 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
16110 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16120 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
16130 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
16140 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
16150 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
16160 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
16170 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
16180 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
16190 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
161a0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
161b0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
161c0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
161d0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
161e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
161f0 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
16200 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
16210 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
16220 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
16230 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
16240 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
16250 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
16260 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
16270 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
16280 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
16290 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
162a0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
162b0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
162c0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
162d0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
162e0 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
162f0 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
16300 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  alue..** </dl>.*
16310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16320 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
16330 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
16340 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16350 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
16360 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
16370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16380 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
16390 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
163a0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
163b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
163c0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
163d0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
163e0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
163f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16400 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
16410 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
16420 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16430 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16440 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
16450 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
16460 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16470 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16480 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
16490 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
164a0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
164b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
164c0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
164d0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
164e0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
164f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16500 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
16510 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
16520 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
16530 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16540 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
16550 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16560 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
16570 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16580 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
16590 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
165a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
165b0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
165c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
165d0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
165e0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
165f0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
16600 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16610 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
16620 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
16630 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16640 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
16650 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16660 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16670 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
16680 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
16690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
166a0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
166b0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
166c0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
166d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
166e0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
166f0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
16700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16710 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
16720 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
16730 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
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 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
16760 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
16770 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
16780 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
16790 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
167a0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
167b0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
167c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
167d0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
167e0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
167f0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
16800 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16810 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
16820 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
16830 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
16840 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16850 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16860 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
16870 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
16880 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16890 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
168a0 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
168b0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
168c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
168d0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
168e0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
168f0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
16900 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ma */../*.** CAP
16910 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
16920 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
16930 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
16940 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
16950 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
16960 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
16970 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16980 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
16990 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
169a0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
169b0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
169c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
169d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
169e0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
169f0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
16a00 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
16a10 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
16a20 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
16a30 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
16a40 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
16a50 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
16a60 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
16a70 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
16a80 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
16a90 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
16aa0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
16ab0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
16ac0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
16ad0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
16ae0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
16af0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
16b00 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
16b10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
16b20 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
16b30 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
16b40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16b50 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
16b60 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
16b70 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
16b80 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
16b90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
16ba0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
16bb0 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
16bc0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
16bd0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
16be0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
16bf0 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
16c00 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
16c10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
16c20 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
16c30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16c40 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
16c50 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
16c60 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
16c70 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
16c80 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
16c90 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
16ca0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
16cb0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
16cc0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
16cd0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16ce0 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
16cf0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
16d00 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
16d10 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
16d20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
16d30 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
16d40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
16d50 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
16d60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
16d70 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
16d80 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
16d90 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
16da0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
16db0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16dc0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
16dd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
16de0 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
16df0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
16e00 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
16e10 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
16e20 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
16e30 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
16e40 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
16e50 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
16e60 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
16e70 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
16e80 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
16e90 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
16ea0 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
16eb0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
16ec0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
16ed0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
16ee0 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
16ef0 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
16f00 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
16f10 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
16f20 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
16f30 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
16f40 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
16f50 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
16f60 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
16f70 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
16f80 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
16f90 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
16fa0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
16fb0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
16fc0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
16fd0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
16fe0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
16ff0 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
17000 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
17010 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
17020 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
17030 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
17040 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
17050 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
17060 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
17070 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
17080 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
17090 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
170a0 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
170b0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
170c0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
170d0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
170e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
170f0 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
17100 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17110 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17120 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17130 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
17140 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
17150 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
17160 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
17170 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17180 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17190 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
171a0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
171b0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
171c0 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
171d0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
171e0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
171f0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
17200 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
17210 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
17220 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
17230 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17240 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
17250 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
17260 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
17270 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
17280 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
17290 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
172a0 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
172b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
172c0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
172d0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
172e0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
172f0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
17300 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
17310 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
17320 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17330 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17340 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17350 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
17360 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
17370 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17380 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17390 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
173a0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
173b0 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
173c0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
173d0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
173e0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
173f0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17400 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17410 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
17420 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
17430 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
17440 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
17450 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
17460 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
17470 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
17480 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
17490 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
174a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
174b0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
174c0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
174d0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
174e0 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
174f0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
17500 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17510 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17520 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17530 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17540 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17550 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
17560 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17570 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
17580 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
17590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
175a0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
175b0 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
175c0 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
175d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
175e0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
175f0 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
17600 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
17610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17620 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
17630 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
17640 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
17650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
17660 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
17670 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
17680 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44   Codes.** METHOD
17690 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
176a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
176b0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
176c0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
176d0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
176e0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
176f0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
17700 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
17710 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
17720 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
17730 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
17740 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
17750 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
17760 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
17770 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
17780 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
17790 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
177a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
177b0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
177c0 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  owid.** METHOD: 
177d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45  sqlite3.**.** ^E
177e0 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73  ach entry in mos
177f0 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20  t SQLite tables 
17800 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54  (except for [WIT
17810 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
17820 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69  es).** has a uni
17830 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
17840 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
17850 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
17860 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
17870 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
17880 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
17890 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
178a0 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
178b0 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
178c0 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
178d0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
178e0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
178f0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
17900 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
17910 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
17920 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
17930 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
17940 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
17950 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
17960 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
17970 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
17980 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
17990 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
179a0 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66  _rowid(D) interf
179b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
179c0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a  [rowid] of the .
179d0 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  ** most recent s
179e0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
179f0 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20  T] into a rowid 
17a00 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61  table or [virtua
17a10 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64  l table].** on d
17a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17a30 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74  on D..** ^Insert
17a40 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
17a50 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
17a60 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a  e not recorded..
17a70 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  ** ^If no succes
17a80 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
17a90 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
17aa0 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
17ab0 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61  curred on the da
17ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17ad0 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71  n D, .** then sq
17ae0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17af0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72  t_rowid(D) retur
17b00 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
17b10 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
17b20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
17b30 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
17b40 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
17b50 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
17b60 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
17b70 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
17b80 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
17b90 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
17ba0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
17bb0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
17bc0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
17bd0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
17be0 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
17bf0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
17c00 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
17c10 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17c20 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
17c30 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
17c40 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
17c50 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
17c60 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
17c70 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
17c80 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
17c90 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
17ca0 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
17cb0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17cc0 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
17cd0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17ce0 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
17cf0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
17d00 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
17d10 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
17d20 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
17d30 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
17d40 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
17d50 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
17d60 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
17d70 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
17d80 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
17d90 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
17da0 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
17db0 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
17dc0 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
17dd0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
17de0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
17df0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
17e00 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
17e10 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
17e20 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
17e30 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
17e40 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
17e50 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
17e60 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
17e70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
17e80 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
17e90 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
17ea0 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
17eb0 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
17ec0 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
17ed0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
17ee0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
17ef0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
17f00 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
17f10 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
17f20 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
17f30 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
17f40 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
17f50 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
17f60 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
17f70 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
17f80 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
17f90 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
17fa0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
17fb0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
17fc0 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
17fd0 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
17fe0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
17ff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18000 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
18010 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18020 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
18030 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
18040 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
18050 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
18060 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
18070 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18080 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
18090 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
180a0 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
180b0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
180c0 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
180d0 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
180e0 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
180f0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
18100 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
18110 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
18120 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
18130 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
18140 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
18150 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
18160 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
18170 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
18180 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
18190 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
181a0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
181b0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
181c0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
181d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
181e0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
181f0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
18200 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
18210 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
18220 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
18230 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
18240 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
18250 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
18260 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
18270 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
18280 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
18290 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
182a0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
182b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
182c0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
182d0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
182e0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
182f0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
18300 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
18310 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
18320 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
18330 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
18340 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
18350 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
18360 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
18370 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
18380 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
18390 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
183a0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
183b0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
183c0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
183d0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
183e0 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
183f0 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
18400 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
18410 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
18420 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
18430 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
18440 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
18450 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
18460 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
18470 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
18480 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
18490 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
184a0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
184b0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
184c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
184d0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
184e0 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
184f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
18500 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
18510 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
18520 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
18530 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
18540 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
18550 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
18560 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
18570 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
18580 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
18590 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
185a0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
185b0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
185c0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
185d0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
185e0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
185f0 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
18600 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18610 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18620 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
18630 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18640 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
18650 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
18660 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
18670 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
18680 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
18690 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
186a0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
186b0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
186c0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
186d0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
186e0 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
186f0 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
18700 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
18710 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18720 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
18730 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
18740 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
18750 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
18760 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
18770 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
18780 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
18790 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
187a0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
187b0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
187c0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
187d0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
187e0 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
187f0 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
18800 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
18810 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
18820 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
18830 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
18840 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
18850 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
18860 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
18870 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
18880 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
18890 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
188a0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
188b0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
188c0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
188d0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
188e0 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
188f0 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
18900 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
18910 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
18920 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
18930 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
18940 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
18950 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
18960 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
18970 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
18980 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
18990 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
189a0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
189b0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
189c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
189d0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
189e0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
189f0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
18a00 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
18a10 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
18a20 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
18a30 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
18a40 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
18a50 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
18a60 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
18a70 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
18a80 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
18a90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18aa0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
18ab0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18ac0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
18ad0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
18ae0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
18af0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
18b00 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
18b10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
18b20 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18b30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18b40 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
18b50 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
18b60 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
18b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
18b80 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
18b90 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
18ba0 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
18bb0 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
18bc0 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
18bd0 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
18be0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
18bf0 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
18c00 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
18c10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18c20 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
18c30 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
18c40 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
18c50 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
18c60 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
18c70 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
18c80 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
18c90 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
18ca0 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
18cb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
18cc0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18cd0 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
18ce0 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
18cf0 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
18d00 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
18d10 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
18d20 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
18d30 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
18d40 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
18d50 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
18d60 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
18d70 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
18d80 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
18d90 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
18da0 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
18db0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
18dc0 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
18dd0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
18de0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
18df0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
18e00 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
18e10 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
18e20 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
18e30 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
18e40 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
18e50 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
18e60 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
18e70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18e80 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
18e90 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
18ea0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
18eb0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
18ec0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
18ed0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
18ee0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
18ef0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
18f00 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18f10 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18f20 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
18f30 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
18f40 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
18f50 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
18f60 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18f70 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
18f80 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
18f90 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
18fa0 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
18fb0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
18fc0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
18fd0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
18fe0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
18ff0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
19000 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
19010 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
19020 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
19030 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
19040 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
19050 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
19060 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
19070 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
19080 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
19090 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
190a0 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
190b0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
190c0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
190d0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
190e0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
190f0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
19100 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
19110 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
19120 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
19130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19140 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
19150 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
19160 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
19170 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19180 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
19190 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
191a0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
191b0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
191c0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
191d0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
191e0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
191f0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
19200 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
19210 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
19220 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
19230 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
19240 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
19250 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
19260 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
19270 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
19280 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
19290 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
192a0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
192b0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
192c0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
192d0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
192e0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
192f0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
19300 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
19310 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
19320 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
19330 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
19340 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
19350 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
19360 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
19370 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
19380 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
19390 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
193a0 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
193b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
193c0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
193d0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
193e0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
193f0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
19400 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
19410 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
19420 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
19430 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
19440 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
19450 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
19460 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
19470 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
19480 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
19490 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
194a0 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
194b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
194c0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
194d0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
194e0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
194f0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
19500 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
19510 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
19520 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19530 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
19540 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19550 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
19560 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
19570 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
19580 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
19590 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
195a0 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
195b0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
195c0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
195d0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
195e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
195f0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
19600 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
19610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
19620 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
19630 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
19640 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
19650 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
19660 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
19670 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
19680 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
19690 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
196a0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
196b0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
196c0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
196d0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
196e0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
196f0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
19700 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
19710 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
19720 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
19730 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
19740 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
19750 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
19760 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
19770 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
19780 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
19790 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
197a0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
197b0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
197c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
197d0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
197e0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
197f0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
19800 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
19810 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
19820 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
19830 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
19840 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
19850 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
19860 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
19870 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
19880 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
19890 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
198a0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
198b0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
198c0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
198d0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
198e0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
198f0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
19900 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
19910 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
19920 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
19930 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
19940 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
19950 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
19960 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
19970 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
19980 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
19990 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
199a0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
199b0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
199c0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
199d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
199e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
199f0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
19a00 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
19a10 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
19a20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
19a30 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
19a40 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
19a50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
19a60 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
19a70 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
19a80 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
19a90 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
19aa0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
19ab0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
19ac0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
19ad0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
19ae0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
19af0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
19b00 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
19b10 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
19b20 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19b30 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
19b40 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
19b50 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
19b60 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
19b70 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19b80 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
19b90 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
19ba0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
19bb0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
19bc0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19bd0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
19be0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
19bf0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
19c00 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
19c10 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
19c20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
19c30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
19c40 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
19c50 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19c60 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
19c70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
19c80 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
19c90 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
19ca0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
19cb0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19cc0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
19cd0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
19ce0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
19cf0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
19d00 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
19d10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19d20 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
19d30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19d40 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
19d50 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
19d60 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
19d70 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
19d80 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
19d90 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
19da0 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
19db0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19dc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
19dd0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
19de0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
19df0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
19e00 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
19e10 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
19e20 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
19e30 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
19e40 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
19e50 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
19e60 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
19e70 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
19e80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19e90 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
19ea0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
19eb0 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
19ec0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
19ed0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
19ee0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
19ef0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
19f00 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
19f10 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
19f20 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
19f30 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
19f40 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
19f50 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
19f60 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
19f70 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
19f80 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
19f90 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
19fa0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
19fb0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
19fc0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
19fd0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
19fe0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
19ff0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1a000 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1a010 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1a020 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1a030 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1a040 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1a050 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1a060 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1a070 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1a080 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a090 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1a0a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1a0b0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a0c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1a0d0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1a0e0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1a0f0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1a100 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1a110 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1a120 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1a130 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1a140 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1a150 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1a160 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1a170 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1a180 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1a190 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1a1a0 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1a1b0 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1a1c0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1a1d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1a1e0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1a1f0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1a200 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1a210 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1a220 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1a230 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1a240 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1a250 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1a260 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1a270 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1a280 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1a290 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1a2a0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1a2b0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1a2c0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1a2d0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1a2e0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1a2f0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1a300 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1a310 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1a320 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1a330 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1a340 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1a350 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1a360 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a370 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1a380 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1a390 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1a3a0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1a3b0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1a3c0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1a3d0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1a3e0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1a3f0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1a400 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1a410 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1a420 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1a430 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1a440 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1a450 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1a460 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1a470 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1a480 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1a490 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1a4a0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1a4b0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1a4c0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1a4d0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1a4e0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1a4f0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1a500 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1a510 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1a520 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1a530 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1a540 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1a550 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1a560 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1a570 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1a580 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1a590 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1a5a0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1a5b0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1a5c0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1a5d0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1a5e0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1a5f0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1a600 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1a610 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1a620 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1a630 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1a640 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1a650 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1a660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1a670 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1a680 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1a690 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1a6a0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1a6b0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1a6c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1a6d0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1a6e0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1a6f0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1a700 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1a710 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1a720 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1a730 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1a740 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1a750 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1a760 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1a770 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1a780 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1a790 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1a7a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1a7b0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1a7c0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1a7d0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1a7e0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1a7f0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1a800 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1a810 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1a820 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1a830 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1a840 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1a850 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1a860 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1a870 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1a880 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1a890 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1a8a0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1a8b0 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
1a8c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a8d0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
1a8e0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
1a8f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1a900 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
1a910 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45  sy Timeout.** ME
1a920 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a930 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1a940 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1a950 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1a960 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1a970 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1a980 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1a990 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1a9a0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1a9b0 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1a9c0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1a9d0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1a9e0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1a9f0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1aa00 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1aa10 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1aa20 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1aa30 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1aa40 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1aa50 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1aa60 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1aa70 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1aa80 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1aa90 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1aaa0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1aab0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1aac0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1aad0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1aae0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1aaf0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1ab00 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1ab10 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1ab20 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1ab30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1ab40 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1ab50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ab60 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1ab70 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1ab80 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1ab90 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1aba0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1abb0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1abc0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1abd0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1abe0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1abf0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1ac00 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1ac10 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1ac20 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1ac30 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1ac40 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1ac50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1ac60 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1ac70 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1ac80 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1ac90 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1aca0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1acb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1acc0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1acd0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1ace0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1acf0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1ad00 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1ad10 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1ad20 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1ad30 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1ad40 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1ad50 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1ad60 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1ad70 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1ad80 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1ad90 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1ada0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1adb0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1adc0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1add0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1ade0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
1adf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1ae00 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1ae10 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1ae20 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1ae30 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1ae40 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1ae50 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1ae60 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1ae70 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1ae80 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1ae90 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1aea0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1aeb0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1aec0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1aed0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1aee0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1aef0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1af00 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1af10 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1af20 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1af30 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1af40 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1af50 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1af60 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1af70 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1af80 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1af90 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1afa0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1afb0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1afc0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1afd0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1afe0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1aff0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1b000 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1b010 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1b020 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1b030 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1b040 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1b050 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1b060 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1b070 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1b080 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1b090 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1b0a0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1b0b0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1b0c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1b0d0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1b0e0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1b0f0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1b100 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1b110 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1b120 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1b130 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1b140 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b150 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1b160 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1b170 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1b180 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1b190 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1b1a0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1b1b0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1b1c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b1d0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1b1e0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1b1f0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1b200 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1b210 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1b220 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1b230 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1b240 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1b250 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1b260 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b270 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b280 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1b290 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1b2a0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1b2b0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1b2c0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1b2d0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1b2e0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1b2f0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1b300 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1b310 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1b320 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1b330 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1b340 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b350 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1b360 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1b370 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1b380 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b390 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1b3a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b3b0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1b3c0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1b3d0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1b3e0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1b3f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1b400 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1b410 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b420 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1b430 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b440 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1b450 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b460 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1b470 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1b480 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1b490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1b4a0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1b4b0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1b4c0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1b4d0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1b4e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1b4f0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1b500 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1b510 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1b520 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1b530 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1b540 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1b550 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1b560 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1b570 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1b580 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1b590 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1b5a0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1b5b0 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1b5c0 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1b5d0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1b5e0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1b5f0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1b600 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1b610 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1b620 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1b630 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1b640 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1b650 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1b660 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1b670 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1b680 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1b690 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1b6a0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1b6b0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1b6c0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1b6d0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1b6e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1b6f0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1b700 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1b710 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1b720 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1b730 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1b740 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1b750 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1b760 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1b770 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1b780 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1b790 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b7a0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1b7b0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1b7c0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1b7d0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1b7e0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1b7f0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1b800 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1b810 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1b820 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1b830 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1b840 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1b850 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1b860 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1b870 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1b880 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1b890 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1b8a0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1b8b0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1b8c0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1b8d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1b8e0 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1b8f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b900 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1b910 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1b920 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1b930 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1b940 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1b950 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1b960 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1b970 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1b980 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1b990 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1b9a0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1b9b0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1b9c0 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1b9d0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1b9e0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1b9f0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1ba00 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1ba10 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1ba20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1ba30 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1ba40 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1ba50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1ba60 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1ba70 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1ba80 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1ba90 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1baa0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1bab0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1bac0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1bad0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1bae0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1baf0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1bb00 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1bb10 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65   library..** The
1bb20 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65  se routines unde
1bb30 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74  rstand most of t
1bb40 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f  he common K&R fo
1bb50 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1bb60 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61  ,.** plus some a
1bb70 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74  dditional non-st
1bb80 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20  andard formats, 
1bb90 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a  detailed below..
1bba0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d  ** Note that som
1bbb0 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62  e of the more ob
1bbc0 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67  scure formatting
1bbd0 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65   options from re
1bbe0 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72  cent.** C-librar
1bbf0 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20  y standards are 
1bc00 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69  omitted from thi
1bc10 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1bc20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1bc30 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1bc40 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1bc50 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1bc60 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1bc70 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1bc80 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1bc90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1bca0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1bcb0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1bcc0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1bcd0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1bce0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1bcf0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1bd00 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1bd10 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1bd20 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1bd30 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1bd40 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1bd50 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1bd60 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1bd70 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1bd80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1bd90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1bda0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1bdb0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1bdc0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1bdd0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1bde0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1bdf0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1be00 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1be10 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1be20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1be30 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1be40 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1be50 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1be60 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1be70 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1be80 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1be90 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1bea0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1beb0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1bec0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1bed0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1bee0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1bef0 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1bf00 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1bf10 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1bf20 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1bf30 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1bf40 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1bf50 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1bf60 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1bf70 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1bf80 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1bf90 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1bfa0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1bfb0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1bfc0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1bfd0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1bfe0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1bff0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1c000 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1c010 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1c020 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1c030 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1c040 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1c050 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1c060 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1c070 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1c080 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1c090 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1c0a0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1c0b0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1c0c0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1c0d0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1c0e0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1c0f0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1c100 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1c110 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1c120 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1c130 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1c140 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1c150 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1c160 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1c170 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1c180 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1c190 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1c1a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1c1b0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1c1c0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1c1d0 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1c1e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1c1f0 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1c200 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1c210 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1c220 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1c230 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1c240 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1c250 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1c260 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1c270 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1c280 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1c290 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1c2a0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1c2b0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1c2c0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1c2d0 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22  ", "%w" and "%z"
1c2e0 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1c2f0 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1c300 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1c310 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1c320 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1c330 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1c340 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1c350 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1c360 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1c370 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1c380 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1c390 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1c3a0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1c3b0 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1c3c0 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1c3d0 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1c3e0 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1c3f0 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1c400 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1c410 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1c420 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1c430 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1c440 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1c450 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1c460 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1c470 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c480 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c490 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1c4a0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1c4b0 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1c4c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c4d0 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1c4e0 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1c4f0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1c500 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1c510 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c520 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1c530 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1c540 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1c550 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1c560 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1c570 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1c580 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1c590 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1c5a0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1c5b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c5c0 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1c5d0 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1c5e0 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1c5f0 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1c600 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1c610 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1c620 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1c630 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1c640 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c650 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1c660 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1c670 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1c680 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1c690 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c6a0 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1c6b0 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1c6c0 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1c6d0 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1c6e0 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1c6f0 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1c700 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1c710 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c720 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c730 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1c740 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1c750 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c760 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1c770 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1c780 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1c790 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1c7a0 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1c7b0 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1c7c0 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1c7d0 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1c7e0 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1c7f0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1c800 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1c810 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1c820 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1c830 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1c840 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1c850 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1c860 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1c870 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1c880 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1c890 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1c8a0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1c8b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1c8c0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1c8d0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1c8e0 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1c8f0 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1c900 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1c910 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1c920 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1c930 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1c940 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1c950 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1c960 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1c970 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1c980 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1c990 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1c9a0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1c9b0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1c9c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c9d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1c9e0 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1c9f0 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1ca00 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1ca10 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1ca20 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1ca30 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1ca40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1ca50 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20  *.** ^(The "%w" 
1ca60 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1ca70 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65  n is like "%q" e
1ca80 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78  xcept that it ex
1ca90 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63  pects to.** be c
1caa0 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20  ontained within 
1cab0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e  double-quotes in
1cac0 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20  stead of single 
1cad0 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a  quotes, and it.*
1cae0 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f  * escapes the do
1caf0 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61  uble-quote chara
1cb00 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  cter instead of 
1cb10 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65  the single-quote
1cb20 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e  .** character.)^
1cb30 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61    The "%w" forma
1cb40 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
1cb50 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66  intended for saf
1cb60 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a  ely inserting.**
1cb70 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
1cb80 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63  n names into a c
1cb90 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73  onstructed SQL s
1cba0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1cbb0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1cbc0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1cbd0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1cbe0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1cbf0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1cc00 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1cc10 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1cc20 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1cc30 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1cc40 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1cc50 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1cc60 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
1cc70 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
1cc80 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1cc90 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1cca0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1ccb0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1ccc0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
1ccd0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
1cce0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ccf0 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
1cd00 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1cd10 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1cd20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1cd30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cd40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1cd50 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1cd60 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1cd70 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1cd80 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1cd90 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1cda0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1cdb0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1cdc0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1cdd0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1cde0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1cdf0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1ce00 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1ce10 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1ce20 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1ce30 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1ce40 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1ce50 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1ce60 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1ce70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ce80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1ce90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1cea0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1ceb0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1cec0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1ced0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1cee0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1cef0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1cf00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1cf10 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1cf20 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1cf30 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1cf40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1cf50 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1cf60 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1cf70 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cf80 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1cf90 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1cfa0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1cfb0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1cfc0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1cfd0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1cfe0 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1cff0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1d000 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1d010 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1d020 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1d030 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1d040 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1d050 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1d060 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1d070 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1d080 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1d090 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1d0a0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1d0b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1d0c0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1d0d0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1d0e0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1d0f0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1d100 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1d110 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1d120 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1d130 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1d140 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1d150 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1d160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1d170 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1d180 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1d190 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1d1a0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1d1b0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1d1c0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1d1d0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1d1e0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1d1f0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1d200 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1d210 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1d220 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1d230 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1d240 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1d250 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1d260 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1d270 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1d280 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1d290 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1d2a0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1d2b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1d2c0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1d2d0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d2e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1d2f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1d300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d310 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d320 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1d330 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1d340 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1d350 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1d360 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1d370 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1d380 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1d390 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d3a0 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1d3b0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1d3c0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1d3d0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1d3e0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1d3f0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1d400 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1d410 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1d420 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1d430 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1d440 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d450 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1d460 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1d470 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1d480 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1d490 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1d4a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d4b0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1d4c0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1d4d0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1d4e0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1d4f0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1d500 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1d510 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1d520 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1d530 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1d540 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1d550 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1d560 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1d570 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1d580 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1d590 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1d5a0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1d5b0 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1d5c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1d5d0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1d5e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1d5f0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1d600 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1d610 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1d620 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1d630 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1d640 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1d650 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d660 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1d670 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1d680 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1d690 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1d6a0 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1d6b0 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1d6c0 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1d6d0 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1d6e0 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1d6f0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1d700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d710 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1d720 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d730 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1d740 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d750 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1d760 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1d770 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1d780 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1d790 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1d7a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1d7b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d7c0 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1d7d0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1d7e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1d7f0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1d800 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1d810 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1d820 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1d830 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1d840 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1d850 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1d860 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1d870 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1d880 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1d890 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1d8a0 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1d8b0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1d8c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1d8d0 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1d8e0 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1d8f0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1d900 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1d910 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1d920 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1d930 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1d940 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1d950 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1d960 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1d970 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1d980 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1d990 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1d9a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d9b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d9c0 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1d9d0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1d9e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1d9f0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1da00 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1da10 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1da20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1da30 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1da40 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1da50 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1da60 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1da70 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1da80 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1da90 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1daa0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1dab0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1dac0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1dad0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1dae0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1daf0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1db00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1db10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1db20 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1db30 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1db40 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1db50 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1db60 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1db70 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1db80 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1db90 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1dba0 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1dbb0 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1dbc0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1dbd0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1dbe0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1dbf0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1dc00 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1dc10 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1dc20 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1dc30 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1dc40 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1dc50 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1dc60 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1dc70 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1dc80 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1dc90 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1dca0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1dcb0 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1dcc0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1dcd0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1dce0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1dcf0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1dd00 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1dd10 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1dd20 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1dd30 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1dd40 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1dd50 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1dd60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1dd70 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1dd80 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1dd90 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1dda0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1ddb0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1ddc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ddd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1dde0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1ddf0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1de00 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1de10 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1de20 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1de30 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1de40 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1de50 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1de60 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1de70 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1de80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1de90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1dea0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1deb0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1dec0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1ded0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73  lite3_malloc64(s
1dee0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1def0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1df00 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1df10 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1df20 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
1df30 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
1df40 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1df50 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c  free(void*);.sql
1df60 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69  ite3_uint64 sqli
1df70 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29  te3_msize(void*)
1df80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1df90 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1dfa0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1dfb0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1dfc0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1dfd0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1dfe0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1dff0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1e000 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e010 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1e020 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1e030 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1e040 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1e050 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1e060 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1e070 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1e080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1e090 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1e0a0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1e0b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1e0c0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1e0d0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1e0e0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1e0f0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1e100 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1e110 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1e120 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1e130 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1e140 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1e150 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e160 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1e170 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1e180 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1e190 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1e1a0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1e1b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e1c0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1e1d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e1e0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1e1f0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1e200 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1e210 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1e220 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1e230 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1e240 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1e250 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1e260 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1e270 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1e280 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1e290 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e2a0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1e2b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1e2c0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1e2d0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1e2e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1e2f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1e300 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1e310 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1e320 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1e330 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e340 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1e350 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1e360 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1e370 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e380 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1e390 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1e3a0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1e3b0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1e3c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1e3d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1e3e0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1e3f0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1e400 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1e410 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1e420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1e430 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1e440 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1e450 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1e460 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1e470 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1e480 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1e490 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1e4a0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1e4b0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1e4c0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1e4d0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1e4e0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1e4f0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1e500 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1e510 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1e520 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1e530 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1e540 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1e550 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1e560 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1e570 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1e580 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1e590 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1e5a0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1e5b0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1e5c0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1e5d0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1e5e0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1e5f0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1e600 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1e610 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1e620 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1e630 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e640 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1e650 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1e660 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1e670 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
1e680 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
1e690 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
1e6a0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1e6b0 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
1e6c0 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
1e6d0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1e6e0 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
1e6f0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1e700 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
1e710 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1e720 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1e730 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1e740 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1e750 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1e760 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1e770 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
1e780 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
1e790 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1e7a0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1e7b0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1e7c0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1e7d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1e7e0 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1e7f0 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f  ** method..*/.vo
1e800 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1e810 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1e820 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1e830 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1e840 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1e850 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  on Callbacks.** 
1e860 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1e870 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1e880 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1e890 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e8a0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1e8b0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1e8c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1e8d0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1e8e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1e8f0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1e900 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e910 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1e920 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1e930 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1e940 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1e950 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1e960 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1e970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1e980 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1e990 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1e9a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e9b0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1e9c0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1e9d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1e9e0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1e9f0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1ea00 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1ea10 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1ea20 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1ea30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ea40 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1ea50 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1ea60 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1ea70 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1ea80 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1ea90 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1eaa0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1eab0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1eac0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1ead0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1eae0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1eaf0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1eb00 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1eb10 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1eb20 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1eb30 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1eb40 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1eb50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1eb60 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1eb70 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1eb80 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1eb90 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1eba0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1ebb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1ebc0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1ebd0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1ebe0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1ebf0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1ec00 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1ec10 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1ec20 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1ec30 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1ec40 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1ec50 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1ec60 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1ec70 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1ec80 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1ec90 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1eca0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1ecb0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1ecc0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1ecd0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1ece0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1ecf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ed00 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1ed10 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1ed20 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1ed30 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1ed40 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1ed50 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1ed60 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1ed70 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1ed80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1ed90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1eda0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1edb0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1edc0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1edd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ede0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1edf0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1ee00 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1ee10 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1ee20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1ee30 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1ee40 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1ee50 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1ee60 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1ee70 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1ee80 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1ee90 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1eea0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1eeb0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1eec0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1eed0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1eee0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1eef0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1ef00 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1ef10 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1ef20 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1ef30 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1ef40 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1ef50 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1ef60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ef70 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1ef80 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1ef90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1efa0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1efb0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1efc0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1efd0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1efe0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1eff0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1f000 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1f010 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1f020 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1f030 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1f040 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1f050 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1f060 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1f070 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1f080 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1f090 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1f0a0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1f0b0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1f0c0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1f0d0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1f0e0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1f0f0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1f100 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1f110 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1f120 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1f130 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1f140 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1f150 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1f160 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1f170 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1f180 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1f190 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1f1a0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1f1b0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1f1c0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1f1d0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1f1e0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1f1f0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1f200 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1f210 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1f220 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1f230 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1f240 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1f250 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1f260 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1f270 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1f280 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1f290 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1f2a0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1f2b0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1f2c0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1f2d0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1f2e0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1f2f0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1f300 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1f310 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1f320 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1f330 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1f340 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1f350 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1f360 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1f370 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1f380 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1f390 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1f3a0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1f3b0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1f3c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1f3d0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1f3e0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1f3f0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1f400 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1f410 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1f420 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1f430 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1f440 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1f450 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1f460 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1f470 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1f480 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1f490 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1f4a0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1f4b0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1f4c0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1f4d0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1f4e0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1f4f0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1f500 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1f510 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1f520 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1f530 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1f540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f550 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1f560 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1f570 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1f580 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1f590 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1f5a0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1f5b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1f5c0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1f5d0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1f5e0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1f5f0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1f600 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1f610 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f620 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1f630 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1f640 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1f650 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1f660 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1f670 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1f680 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1f690 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1f6a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f6b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1f6c0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1f6d0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1f6e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1f6f0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1f700 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1f710 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1f720 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1f730 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f740 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1f750 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1f760 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1f770 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1f780 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1f790 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f7a0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1f7b0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1f7c0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1f7d0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1f7e0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1f7f0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1f800 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1f810 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1f820 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1f830 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1f840 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1f850 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f860 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1f870 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1f880 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f890 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1f8a0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1f8b0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1f8c0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1f8d0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1f8e0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1f8f0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1f900 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1f910 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1f920 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1f930 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1f940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f950 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1f960 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1f970 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1f980 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1f990 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1f9a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1f9b0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1f9c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1f9d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1f9e0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1f9f0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1fa00 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1fa10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1fa20 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1fa30 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1fa40 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1fa50 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1fa60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1fa70 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1fa80 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1fa90 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1faa0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1fab0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1fac0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1fad0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1fae0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1faf0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1fb00 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1fb10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1fb20 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1fb30 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1fb40 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1fb50 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1fb60 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1fb70 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1fb80 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f  so used as a [co
1fb90 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f  nflict resolutio
1fba0 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72  n mode].** retur
1fbb0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ned from the [sq
1fbc0 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
1fbd0 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
1fbe0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
1fbf0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
1fc00 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
1fc10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
1fc20 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
1fc30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
1fc40 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
1fc50 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
1fc60 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
1fc70 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
1fc80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1fc90 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
1fca0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1fcb0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1fcc0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
1fcd0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
1fce0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1fcf0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
1fd00 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
1fd10 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
1fd20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
1fd30 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
1fd40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1fd50 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1fd60 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
1fd70 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1fd80 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
1fd90 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1fda0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
1fdb0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
1fdc0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
1fdd0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fde0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
1fdf0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1fe00 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
1fe10 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
1fe20 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
1fe30 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
1fe40 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
1fe50 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1fe60 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
1fe70 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1fe80 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1fe90 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1fea0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1feb0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1fec0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1fed0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1fee0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1fef0 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
1ff00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1ff10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ff20 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
1ff30 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1ff40 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
1ff50 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
1ff60 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
1ff70 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1ff80 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1ff90 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
1ffa0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1ffb0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1ffc0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1ffd0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1ffe0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
1fff0 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
20000 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
20010 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
20020 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
20030 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
20040 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
20050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20070 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
20080 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
20090 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
200a0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
200b0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
200c0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
200d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
200e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
200f0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
20100 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
20110 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20120 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20140 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
20150 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
20160 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
20170 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20190 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
201a0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
201b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
201c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
201d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
201e0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
201f0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
20200 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
20210 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20220 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20230 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
20240 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
20250 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20260 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20270 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20280 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
20290 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
202a0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
202b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
202c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
202d0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
202e0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
202f0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
20300 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20310 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
20320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20330 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
20340 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20350 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20360 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
20370 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
20380 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
20390 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
203a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
203b0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
203c0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
203d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
203e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
203f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20400 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
20410 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
20420 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20430 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20440 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20450 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
20460 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
20470 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20480 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20490 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
204a0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
204b0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
204c0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
204d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
204e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
204f0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
20500 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
20510 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
20520 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20530 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20540 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
20550 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
20560 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
20570 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20580 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20590 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
205a0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
205b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
205c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
205d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
205e0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
205f0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
20600 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20610 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20620 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20630 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
20640 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
20650 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
20660 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
20670 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
20680 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
20690 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
206a0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
206b0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
206c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
206d0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
206e0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
206f0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
20700 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
20720 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
20730 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
20740 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
20750 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20760 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
20770 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
20780 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
20790 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
207a0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
207b0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
207c0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
207d0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
207e0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
207f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20800 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
20810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20820 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
20830 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
20840 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20850 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
20860 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
20870 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
20880 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
20890 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
208a0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
208b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
208c0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
208d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
208e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
208f0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
20900 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
20910 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20920 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20930 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20940 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
20950 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
20960 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20970 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
20980 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20990 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
209a0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
209b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
209c0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
209d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
209e0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
209f0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
20a00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20a10 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
20a20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20a30 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
20a40 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
20a50 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
20a60 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
20a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20a80 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
20a90 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
20aa0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
20ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20ac0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
20ad0 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c       33   /* NUL
20ae0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
20af0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20b10 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
20b20 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
20b30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
20b40 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  te3.**.** These 
20b50 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
20b60 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
20b70 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
20b80 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
20b90 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
20ba0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
20bb0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
20bc0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
20bd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20be0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
20bf0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
20c00 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
20c10 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
20c20 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
20c30 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
20c40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
20c50 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
20c60 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
20c70 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
20c80 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
20c90 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
20ca0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
20cb0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
20cc0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
20cd0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
20ce0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
20cf0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
20d00 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
20d10 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
20d20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
20d30 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
20d40 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
20d50 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
20d60 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
20d70 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
20d80 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
20d90 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
20da0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   The [SQLITE_TRA
20db0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
20dc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
20dd0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
20de0 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c  o limit.** the l
20df0 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20  ength of [bound 
20e00 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e  parameter] expan
20e10 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70  sion in the outp
20e20 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72  ut of sqlite3_tr
20e30 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ace()..**.** ^Th
20e40 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
20e50 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
20e60 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
20e70 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
20e80 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
20e90 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
20ea0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
20eb0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
20ec0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
20ed0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
20ee0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
20ef0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
20f00 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
20f10 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
20f20 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
20f30 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
20f40 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
20f50 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
20f60 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
20f70 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
20f80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
20f90 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
20fa0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
20fb0 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
20fc0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
20fd0 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
20fe0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
20ff0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
21000 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
21010 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
21020 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
21030 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
21040 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
21050 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
21060 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
21070 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
21080 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
21090 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
210a0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
210b0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
210c0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
210d0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
210e0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
210f0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
21100 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
21110 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
21120 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
21130 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
21140 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
21150 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
21160 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
21170 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
21180 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
21190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
211a0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
211b0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
211c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
211d0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
211e0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
211f0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
21200 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
21210 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
21220 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
21230 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
21240 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
21250 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
21260 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
21270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21280 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
21290 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
212a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
212b0 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
212c0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
212d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
212e0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
212f0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
21300 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
21310 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
21320 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
21330 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
21340 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
21350 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
21360 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
21370 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
21380 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
21390 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
213a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
213b0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
213c0 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
213d0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
213e0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
213f0 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
21400 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
21410 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
21420 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
21430 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
21440 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
21450 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
21460 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
21470 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
21480 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
21490 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
214a0 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
214b0 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
214c0 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
214d0 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
214e0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
214f0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
21500 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
21510 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
21520 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
21530 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
21540 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
21550 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
21560 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
21570 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
21580 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
21590 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
215a0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
215b0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
215c0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
215d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
215e0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
215f0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
21600 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
21610 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
21620 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
21630 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
21640 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
21650 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
21660 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
21670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21680 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
21690 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
216a0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
216b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
216c0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
216d0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
216e0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
216f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21700 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
21710 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
21720 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
21730 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
21740 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
21750 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
21760 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
21770 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
21780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
21790 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
217a0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
217b0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
217c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
217d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
217e0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
217f0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
21800 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
21810 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
21820 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
21830 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
21840 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21850 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
21860 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
21870 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21880 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
21890 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
218a0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
218b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
218c0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
218d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
218e0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
218f0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
21900 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
21910 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
21920 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
21930 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
21940 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
21950 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
21960 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
21970 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
21980 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
21990 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
219a0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
219b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
219c0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
219d0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
219e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
219f0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
21a00 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
21a10 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
21a20 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
21a30 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
21a40 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
21a50 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
21a60 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
21a70 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
21a80 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
21a90 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
21aa0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
21ab0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
21ac0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
21ad0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
21ae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
21af0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
21b00 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
21b10 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
21b20 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
21b30 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
21b40 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
21b50 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
21b60 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
21b70 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
21b80 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
21b90 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
21ba0 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
21bb0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
21bc0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
21bd0 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
21be0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
21bf0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
21c00 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
21c10 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
21c20 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
21c30 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
21c40 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
21c50 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
21c60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
21c70 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
21c80 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
21c90 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
21ca0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
21cb0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
21cc0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
21cd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
21ce0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
21cf0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
21d00 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
21d10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
21d20 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
21d30 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
21d40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
21d50 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
21d60 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
21d70 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
21d80 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
21d90 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
21da0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
21db0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
21dc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
21dd0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
21de0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
21df0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
21e00 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
21e10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
21e20 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
21e30 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21e40 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
21e50 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21e60 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
21e70 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
21e80 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
21e90 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
21ea0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
21eb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21ec0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21ed0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
21ee0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
21ef0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
21f00 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
21f10 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
21f20 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
21f30 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
21f40 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21f50 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
21f60 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
21f70 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
21f80 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
21f90 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
21fa0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
21fb0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
21fc0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
21fd0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21fe0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
21ff0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
22000 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
22010 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
22020 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
22030 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
22040 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
22050 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
22060 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
22070 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
22080 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
22090 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
220a0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
220b0 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
220c0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
220d0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
220e0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
220f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
22100 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
22110 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
22120 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
22130 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
22140 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
22150 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
22160 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
22170 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
22180 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
22190 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
221a0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
221b0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
221c0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
221d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
221e0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
221f0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
22200 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
22210 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
22220 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
22230 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
22240 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
22250 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22260 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
22270 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
22280 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
22290 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
222a0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
222b0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
222c0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
222d0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
222e0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
222f0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
22300 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
22310 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
22320 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22330 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
22340 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
22350 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
22360 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
22370 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
22380 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
22390 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
223a0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
223b0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
223c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
223d0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
223e0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
223f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
22400 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
22410 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
22420 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
22430 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
22440 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
22450 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
22460 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
22470 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
22480 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
22490 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
224a0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
224b0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
224c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
224d0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
224e0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
224f0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
22500 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
22510 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
22520 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
22530 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22540 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
22550 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
22560 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
22570 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
22580 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
22590 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
225a0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
225b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
225c0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
225d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
225e0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
225f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
22600 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
22610 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
22620 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
22630 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
22640 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
22650 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
22660 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
22670 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
22680 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
22690 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
226a0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
226b0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
226c0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
226d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
226e0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
226f0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
22700 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
22710 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
22720 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
22730 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
22740 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
22750 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
22760 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
22770 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
22780 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
22790 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
227a0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
227b0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
227c0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
227d0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
227e0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
227f0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
22800 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
22810 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
22820 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
22830 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
22840 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
22850 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
22860 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
22870 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
22880 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
22890 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
228a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
228b0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
228c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
228d0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
228e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
228f0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
22900 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
22910 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
22920 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
22930 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
22940 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
22950 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
22960 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
22970 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
22980 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
22990 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
229a0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
229b0 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
229c0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
229d0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
229e0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
229f0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
22a00 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
22a10 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
22a20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22a30 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
22a40 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
22a50 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
22a60 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
22a70 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
22a80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
22a90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
22aa0 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
22ab0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
22ac0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
22ad0 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
22ae0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
22af0 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
22b00 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
22b10 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
22b20 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
22b30 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
22b40 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
22b50 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
22b60 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
22b70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
22b80 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
22b90 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
22ba0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
22bb0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
22bc0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
22bd0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
22be0 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
22bf0 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
22c00 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
22c10 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
22c20 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
22c30 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
22c40 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
22c50 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
22c60 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
22c70 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
22c80 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
22c90 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
22ca0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
22cb0 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
22cc0 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
22cd0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
22ce0 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
22cf0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
22d00 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
22d10 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
22d20 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
22d30 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22d40 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
22d50 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
22d60 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
22d70 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
22d80 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
22d90 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
22da0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22db0 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
22dc0 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
22dd0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
22de0 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
22df0 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
22e00 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
22e10 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
22e20 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
22e30 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
22e40 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
22e50 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
22e60 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73  .** ^(On windows
22e70 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
22e80 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
22e90 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
22ea0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
22eb0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
22ec0 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  ").)^.**.** [[co
22ed0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
22ee0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
22ef0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
22f00 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
22f10 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
22f20 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
22f30 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
22f40 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
22f50 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
22f60 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
22f70 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
22f80 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62  SQLite and its b
22f90 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20  uilt-in [VFSes] 
22fa0 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
22fb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
22fc0 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
22fd0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
22fe0 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
22ff0 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
23000 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
23010 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
23020 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
23030 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
23040 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
23050 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
23060 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
23070 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
23080 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
23090 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
230a0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
230b0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
230c0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
230d0 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
230e0 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
230f0 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
23100 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
23110 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
23120 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
23130 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
23140 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
23150 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
23160 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
23170 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
23180 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
23190 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
231a0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
231b0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
231c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
231d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
231e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
231f0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
23200 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
23210 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
23220 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
23230 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
23240 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
23250 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
23260 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
23270 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
23280 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
23290 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
232a0 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
232b0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
232c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
232d0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
232e0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
232f0 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
23300 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
23310 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
23320 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
23330 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
23340 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
23350 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
23360 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
23370 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
23380 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
23390 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
233a0 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
233b0 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
233c0 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
233d0 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
233e0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
233f0 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
23400 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
23410 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
23420 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
23430 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
23440 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
23450 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
23460 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
23470 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
23480 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
23490 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
234a0 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
234b0 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
234c0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
234d0 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
234e0 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
234f0 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
23500 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
23510 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
23520 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
23530 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
23540 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
23550 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
23560 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
23570 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
23580 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
23590 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
235a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
235b0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
235c0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
235d0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
235e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
235f0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
23600 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
23610 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
23620 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
23630 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
23640 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
23650 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
23660 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
23670 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
23680 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
23690 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
236a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
236b0 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
236c0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
236d0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
236e0 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
236f0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
23700 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
23710 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
23720 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
23730 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
23740 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
23750 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
23760 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
23770 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
23780 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
23790 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
237a0 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79  ior requested by
237b0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
237c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
237d0 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
237e0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
237f0 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  CHE flag..**.** 
23800 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62   <li> <b>psow</b
23810 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72  >: ^The psow par
23820 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73  ameter indicates
23830 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
23840 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65  the.**     [powe
23850 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d  rsafe overwrite]
23860 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f   property does o
23870 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79  r does not apply
23880 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73   to the.**     s
23890 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20  torage media on 
238a0 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61  which the databa
238b0 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e  se file resides.
238c0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
238d0 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65  nolock</b>: ^The
238e0 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65   nolock paramete
238f0 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
23900 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a  uery parameter.*
23910 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73  *     which if s
23920 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65  et disables file
23930 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c   locking in roll
23940 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64  back journal mod
23950 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20  es.  This.**    
23960 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61   is useful for a
23970 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62  ccessing a datab
23980 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73  ase on a filesys
23990 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  tem that does no
239a0 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74  t.**     support
239b0 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69   locking.  Cauti
239c0 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f  on:  Database co
239d0 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72  rruption might r
239e0 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20  esult if two.** 
239f0 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63      or more proc
23a00 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74  esses write to t
23a10 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
23a20 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20   and any one of 
23a30 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f  those.**     pro
23a40 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f  cesses uses nolo
23a50 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ck=1..**.**  <li
23a60 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f  > <b>immutable</
23a70 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62  b>: ^The immutab
23a80 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  le parameter is 
23a90 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a  a boolean query.
23aa0 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
23ab0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
23ac0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
23ad0 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64  e file is stored
23ae0 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d   on.**     read-
23af0 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68  only media.  ^Wh
23b00 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20  en immutable is 
23b10 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75  set, SQLite assu
23b20 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
23b30 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c      database fil
23b40 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  e cannot be chan
23b50 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70  ged, even by a p
23b60 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68  rocess with high
23b70 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c  er.**     privil
23b80 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ege, and so the 
23b90 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
23ba0 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64  ed read-only and
23bb0 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20   all locking.** 
23bc0 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64      and change d
23bd0 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61  etection is disa
23be0 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20  bled.  Caution: 
23bf0 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75  Setting the immu
23c00 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f  table.**     pro
23c10 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62  perty on a datab
23c20 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f  ase file that do
23c30 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67  es in fact chang
23c40 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20  e can result.** 
23c50 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74      in incorrect
23c60 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61   query results a
23c70 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  nd/or [SQLITE_CO
23c80 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a  RRUPT] errors..*
23c90 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20  *     See also: 
23ca0 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
23cb0 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20  MUTABLE]..**    
23cc0 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a     .** </ul>.**.
23cd0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
23ce0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
23cf0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
23d00 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
23d10 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
23d20 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
23d30 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23d40 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
23d50 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
23d60 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
23d70 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
23d80 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
23d90 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
23da0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
23db0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
23dc0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
23dd0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
23de0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
23df0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
23e00 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
23e10 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
23e20 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
23e30 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
23e40 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
23e50 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
23e60 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
23e70 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
23e80 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23e90 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
23ea0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
23eb0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
23ec0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
23ed0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
23ee0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
23ef0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
23f00 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23f10 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
23f20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
23f30 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
23f40 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
23f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
23f60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
23f70 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
23f80 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
23f90 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
23fa0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
23fb0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
23fc0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
23fd0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
23fe0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
23ff0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
24000 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
24010 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
24020 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
24030 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
24040 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
24050 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
24060 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
24070 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
24080 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
24090 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
240a0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
240b0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
240c0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
240d0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
240e0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
240f0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
24100 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
24110 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
24120 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
24130 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
24140 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
24150 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
24160 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
24170 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
24180 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
24190 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
241a0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
241b0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
241c0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
241d0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
241e0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
241f0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
24200 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
24210 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
24220 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
24230 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
24240 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
24250 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
24260 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
24270 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
24280 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c  s=unix-dotfile <
24290 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
242a0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
242b0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
242c0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
242d0 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c  VFS "unix-dotfil
242e0 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  e".**          t
242f0 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  hat uses dot-fil
24300 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70  es in place of p
24310 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f  osix advisory lo
24320 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cking..** <tr><t
24330 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
24340 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
24350 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
24360 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
24370 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
24380 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
24390 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
243a0 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
243b0 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
243c0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
243d0 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
243e0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
243f0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
24400 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
24410 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
24420 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
24430 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
24440 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
24450 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
24460 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
24470 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
24480 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
24490 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
244a0 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
244b0 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
244c0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
244d0 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
244e0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
244f0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
24500 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
24510 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
24520 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
24530 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
24540 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
24550 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
24560 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
24570 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
24580 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
24590 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
245a0 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
245b0 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
245c0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
245d0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
245e0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
245f0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
24600 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
24610 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
24620 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
24630 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
24640 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
24650 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
24660 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
24670 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
24680 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
24690 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
246a0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
246b0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
246c0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
246d0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
246e0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
246f0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
24700 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
24710 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
24720 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
24730 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
24740 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
24750 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
24760 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
24770 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
24780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24790 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
247a0 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
247b0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
247c0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
247d0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
247e0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
247f0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
24800 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
24810 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
24820 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24830 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
24840 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
24850 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
24860 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
24870 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
24880 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
24890 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
248a0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
248b0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
248c0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
248d0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
248e0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
248f0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
24900 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
24910 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
24920 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
24930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
24940 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
24950 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
24960 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
24970 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
24980 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
24990 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
249a0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
249b0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
249c0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
249d0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
249e0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
249f0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
24a00 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
24a10 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
24a20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24a30 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
24a40 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
24a50 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
24a60 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
24a70 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
24a80 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
24a90 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
24aa0 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
24ab0 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
24ac0 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
24ad0 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
24ae0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
24af0 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
24b00 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
24b10 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24b20 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
24b30 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24b40 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
24b50 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
24b60 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
24b70 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
24b80 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
24b90 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
24ba0 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
24bb0 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
24bc0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
24bd0 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
24be0 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
24bf0 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
24c00 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
24c10 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
24c20 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
24c30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24c40 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24c50 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
24c60 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
24c70 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
24c80 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
24c90 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
24ca0 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
24cb0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24cc0 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
24cd0 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
24ce0 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
24cf0 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
24d00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24d10 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
24d20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
24d30 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
24d40 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
24d50 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
24d60 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24d70 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
24d80 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
24d90 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
24da0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
24db0 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
24dc0 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
24dd0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
24de0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
24df0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24e00 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
24e10 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
24e20 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
24e30 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
24e40 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
24e50 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
24e60 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
24e70 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
24e80 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
24e90 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
24ea0 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
24eb0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24ec0 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
24ed0 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
24ee0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
24ef0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24f00 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
24f10 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
24f20 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
24f30 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
24f40 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
24f50 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
24f60 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
24f70 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
24f80 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
24f90 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
24fa0 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
24fb0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
24fc0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
24fd0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24fe0 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
24ff0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
25000 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
25010 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
25020 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
25030 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
25040 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
25050 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
25060 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
25070 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
25080 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
25090 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
250a0 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
250b0 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
250c0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
250d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
250e0 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
250f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
25100 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
25110 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
25120 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
25130 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
25140 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
25150 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
25160 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
25170 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
25180 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
25190 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
251a0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
251b0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
251c0 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
251d0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
251e0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
251f0 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
25200 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
25210 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
25220 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
25230 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
25240 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
25250 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
25260 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
25270 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
25280 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
25290 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
252a0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
252b0 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
252c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
252d0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
252e0 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
252f0 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
25300 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
25310 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
25320 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
25330 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
25340 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lite3.**.** ^If 
25350 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
25360 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
25370 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
25380 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  th .** [database
25390 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66   connection] D f
253a0 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ailed, then the 
253b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
253c0 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  D) interface.** 
253d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
253e0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
253f0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
25400 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
25410 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c  that.** API call
25420 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74  ..** If the most
25430 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
25440 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c   was successful,
25450 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
25460 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
25470 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
25480 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
25490 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
254a0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
254b0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
254c0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
254d0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
254e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
254f0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
25500 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
25510 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
25520 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
25530 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
25540 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
25550 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
25560 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
25570 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
25580 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
25590 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
255a0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
255b0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
255c0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
255d0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
255e0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
255f0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
25600 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
25610 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
25620 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
25630 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
25640 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
25650 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
25660 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
25670 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
25680 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
25690 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
256a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
256b0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
256c0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
256d0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
256e0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
256f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25700 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
25710 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
25720 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
25730 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
25740 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
25750 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
25760 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
25770 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
25780 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
25790 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
257a0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
257b0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
257c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
257d0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
257e0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
257f0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
25800 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
25810 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
25820 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
25830 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
25840 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
25850 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
25860 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
25870 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
25880 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
25890 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
258a0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
258b0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
258c0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
258d0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
258e0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
258f0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
25900 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
25910 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
25920 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
25930 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
25940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25950 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
25960 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
25970 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
25980 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
25990 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
259a0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
259b0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
259c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
259d0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
259e0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
259f0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
25a00 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
25a10 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
25a20 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
25a30 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
25a40 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
25a50 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
25a60 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
25a70 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
25a80 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
25a90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25aa0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
25ab0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
25ac0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
25ad0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
25ae0 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
25af0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
25b00 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
25b10 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
25b20 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
25b30 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
25b40 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
25b50 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
25b60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25b70 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
25b80 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
25b90 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
25ba0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
25bb0 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53  3REF: Prepared S
25bc0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
25bd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
25be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25bf0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
25c00 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
25c10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
25c20 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
25c30 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
25c40 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a   statement that.
25c50 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70  ** has been comp
25c60 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79  iled into binary
25c70 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61   form and is rea
25c80 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  dy to be evaluat
25c90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20  ed..**.** Think 
25ca0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  of each SQL stat
25cb0 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72  ement as a separ
25cc0 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f  ate computer pro
25cd0 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72  gram.  The.** or
25ce0 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20  iginal SQL text 
25cf0 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
25d00 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74   A prepared stat
25d10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a  ement object .**
25d20 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   is the compiled
25d30 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41   object code.  A
25d40 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63  ll SQL must be c
25d50 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a  onverted into a.
25d60 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
25d70 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20  ement before it 
25d80 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a  can be run..**.*
25d90 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65  * The life-cycle
25da0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73   of a prepared s
25db0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
25dc0 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b  usually goes lik
25dd0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
25de0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
25df0 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  e the prepared s
25e00 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
25e10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
25e20 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a  repare_v2()]..**
25e30 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
25e40 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73  s to [parameters
25e50 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
25e60 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
25e70 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
25e80 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
25e90 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
25ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25eb0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
25ec0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
25ed0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
25ee0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
25ef0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25f00 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
25f10 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
25f20 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
25f30 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
25f40 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
25f50 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
25f60 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25f70 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ()]..** </ol>.*/
25f80 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
25f90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
25fa0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
25fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
25fc0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d  time Limits.** M
25fd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
25fe0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
25ff0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
26000 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
26010 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
26020 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
26030 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
26040 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
26050 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
26060 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
26070 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26080 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
26090 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
260a0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
260b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
260c0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
260d0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
260e0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
260f0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
26100 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
26110 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
26120 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
26130 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
26140 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
26150 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
26160 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
26170 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
26180 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
26190 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
261a0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
261b0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
261c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
261d0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
261e0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
261f0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
26200 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
26210 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
26220 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
26230 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
26240 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
26250 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
26260 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
26270 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
26280 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
26290 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
262a0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
262b0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
262c0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
262d0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
262e0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
262f0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
26300 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
26310 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
26320 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
26330 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
26340 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
26350 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
26360 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26370 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
26380 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
26390 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
263a0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
263b0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
263c0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
263d0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
263e0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
263f0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
26400 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
26410 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
26420 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
26430 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
26440 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
26450 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
26460 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
26470 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
26480 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
26490 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
264a0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
264b0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
264c0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
264d0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
264e0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
264f0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
26500 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
26510 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
26520 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
26530 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
26540 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
26550 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
26560 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
26570 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
26580 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
26590 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
265a0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
265b0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
265c0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
265d0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
265e0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
265f0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
26600 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
26610 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
26620 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
26630 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
26640 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
26650 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
26660 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
26670 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
26680 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
26690 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
266a0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
266b0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
266c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
266d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
266e0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
266f0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
26700 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
26710 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
26720 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
26730 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
26740 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
26750 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
26760 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
26770 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
26780 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
26790 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
267a0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
267b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
267c0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
267d0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
267e0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
267f0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
26800 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
26810 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
26820 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
26830 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
26840 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
26850 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
26860 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
26870 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
26880 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
26890 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
268a0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
268b0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
268c0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
268d0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
268e0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
268f0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
26900 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
26910 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
26920 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
26930 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26940 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
26950 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26960 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
26970 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
26980 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
26990 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
269a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
269b0 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
269c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
269d0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
269e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
269f0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
26a00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
26a10 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
26a20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26a30 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
26a40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26a50 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
26a60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26a70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
26a80 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
26a90 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
26aa0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
26ab0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
26ac0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
26ad0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
26ae0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
26af0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
26b00 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
26b10 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
26b20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26b30 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
26b40 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26b50 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
26b60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26b70 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
26b80 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
26b90 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
26ba0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26bb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26bc0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
26bd0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26be0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
26bf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26c00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26c10 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
26c20 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
26c30 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
26c40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26c50 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
26c60 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26c70 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
26c80 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26c90 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
26ca0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
26cb0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
26cc0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
26cd0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
26ce0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
26cf0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
26d00 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
26d10 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
26d20 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
26d30 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
26d40 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
26d50 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
26d60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26d70 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
26d80 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26d90 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
26da0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26db0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26dc0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
26dd0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
26de0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26df0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
26e00 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26e10 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
26e20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26e30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26e40 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
26e50 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
26e60 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
26e70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
26e80 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
26e90 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
26ea0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
26eb0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
26ec0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26ed0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
26ee0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
26ef0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
26f00 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
26f10 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
26f20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26f30 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26f40 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
26f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
26f60 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
26f70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26f80 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
26f90 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
26fa0 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
26fb0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
26fc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26fd0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
26fe0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26ff0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
27000 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
27010 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
27020 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
27030 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
27040 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27050 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
27060 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
27070 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
27080 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
27090 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
270a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
270b0 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
270c0 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
270d0 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
270e0 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
270f0 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
27100 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
27110 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
27120 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
27130 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
27140 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
27150 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
27160 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
27170 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27180 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
27190 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
271a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
271b0 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
271c0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
271d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
271e0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
271f0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
27200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27210 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
27220 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
27230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27240 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
27250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
27260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27270 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
27280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
27290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
272a0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
272b0 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
272c0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
272d0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
272e0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
272f0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
27300 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
27310 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
27320 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
27330 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
27340 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
27350 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
27360 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
27370 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
27380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
27390 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
273a0 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  piler}.** METHOD
273b0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e  : sqlite3.** CON
273c0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
273d0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20  3_stmt.**.** To 
273e0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
273f0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
27400 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
27410 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
27420 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
27430 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
27440 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
27450 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
27460 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
27470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27480 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
27490 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
274a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
274b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
274c0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
274d0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
274e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
274f0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
27500 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
27510 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
27520 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
27530 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
27540 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
27550 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
27560 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
27570 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
27580 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
27590 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
275a0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
275b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
275c0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
275d0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
275e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
275f0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
27600 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
27610 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
27620 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
27630 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
27640 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
27650 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
27660 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
27670 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
27680 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
27690 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
276a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
276b0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
276c0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
276d0 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
276e0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
276f0 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
27700 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
27710 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
27720 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
27730 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
27740 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
27750 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
27760 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
27770 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
27780 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
27790 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
277a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
277b0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
277c0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
277d0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
277e0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
277f0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
27800 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
27810 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
27820 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
27830 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
27840 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
27850 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
27860 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
27870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
27880 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
27890 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
278a0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
278b0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
278c0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
278d0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
278e0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
278f0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
27900 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
27910 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
27920 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
27930 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
27940 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27950 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
27960 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
27970 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
27980 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
27990 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
279a0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
279b0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
279c0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
279d0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
279e0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
279f0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
27a00 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
27a10 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
27a20 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
27a30 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
27a40 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
27a50 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
27a60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
27a70 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
27a80 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
27a90 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
27aa0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
27ab0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
27ac0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
27ad0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
27ae0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
27af0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
27b00 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
27b10 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
27b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27b30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
27b40 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27b50 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
27b60 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
27b70 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
27b80 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
27b90 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
27ba0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
27bb0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
27bc0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
27bd0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
27be0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
27bf0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
27c00 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
27c10 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
27c20 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
27c30 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
27c40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
27c50 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
27c60 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
27c70 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
27c80 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
27c90 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
27ca0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
27cb0 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
27cc0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
27cd0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
27ce0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
27cf0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
27d00 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
27d10 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
27d20 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
27d30 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
27d40 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
27d50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
27d60 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
27d70 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
27d80 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
27d90 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
27da0 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
27db0 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
27dc0 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
27dd0 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
27de0 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
27df0 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
27e00 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
27e10 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
27e20 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
27e30 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
27e40 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
27e50 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
27e60 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
27e70 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
27e80 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
27e90 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
27ea0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
27eb0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
27ec0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
27ed0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
27ee0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
27ef0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
27f00 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
27f10 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
27f20 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
27f30 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
27f40 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
27f50 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
27f60 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
27f70 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
27f80 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
27f90 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
27fa0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
27fb0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
27fc0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
27fd0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
27fe0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
27ff0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
28000 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
28010 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
28020 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
28030 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
28040 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
28050 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
28060 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
28070 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
28080 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
28090 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
280a0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
280b0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
280c0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
280d0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
280e0 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
280f0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
28100 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
28110 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
28120 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
28130 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
28140 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
28150 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
28160 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
28170 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
28180 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
28190 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
281a0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
281b0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
281c0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
281d0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
281e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
281f0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
28200 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
28210 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
28220 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
28230 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
28240 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
28250 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
28260 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
28270 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
28280 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
28290 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
282a0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
282b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
282c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
282d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
282e0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
282f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
28300 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
28310 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
28320 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
28330 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28340 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28350 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28360 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28370 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28380 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28390 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
283a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
283b0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
283c0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
283d0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
283e0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
283f0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
28400 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
28410 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28420 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28430 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
28440 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
28450 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
28460 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
28470 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
28480 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
28490 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
284a0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
284b0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
284c0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
284d0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
284e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
284f0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
28500 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
28510 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
28520 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
28530 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
28540 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
28550 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28560 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
28570 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28580 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
28590 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
285a0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
285b0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
285c0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
285d0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
285e0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
285f0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
28600 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
28610 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
28620 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
28630 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
28640 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
28650 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
28660 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
28670 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
28680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28690 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
286a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
286b0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
286c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
286d0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
286e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
286f0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
28700 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
28710 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
28720 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28730 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
28740 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
28750 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28760 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28770 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28780 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
28790 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
287a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
287b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
287c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
287d0 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
287e0 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20  tatement SQL.** 
287f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
28800 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
28810 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
28820 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
28830 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
28840 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
28850 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
28860 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
28870 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28880 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
28890 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
288a0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
288b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
288c0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
288d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
288e0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
288f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
28900 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
28910 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
28920 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
28930 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
28940 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
28950 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48  Database.** METH
28960 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
28970 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28980 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
28990 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
289a0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
289b0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
289c0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
289d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
289e0 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
289f0 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
28a00 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
28a10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28a20 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
28a30 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
28a40 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28a50 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
28a60 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
28a70 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
28a80 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
28a90 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
28aa0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
28ab0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
28ac0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
28ad0 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
28ae0 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
28af0 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
28b00 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
28b10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
28b20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
28b30 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
28b40 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
28b50 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
28b60 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
28b70 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
28b80 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
28b90 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
28ba0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
28bb0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
28bc0 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
28bd0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
28be0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
28bf0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
28c00 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
28c10 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
28c20 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
28c30 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
28c40 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
28c50 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
28c60 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
28c70 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
28c80 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
28c90 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
28ca0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
28cb0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
28cc0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
28cd0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
28ce0 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
28cf0 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
28d00 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
28d10 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
28d20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
28d30 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
28d40 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
28d50 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
28d60 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
28d70 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
28d80 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
28d90 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
28da0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
28db0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
28dc0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
28dd0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
28de0 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
28df0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
28e00 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
28e10 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
28e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
28e30 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
28e40 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
28e50 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28e60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28e70 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
28e80 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
28e90 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
28ea0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
28eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28ec0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
28ed0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28ee0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
28ef0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28f00 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
28f10 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
28f20 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
28f30 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
28f40 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
28f50 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
28f60 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
28f70 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
28f80 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
28f90 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
28fa0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
28fb0 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f  either run to co
28fc0 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e  mpletion (return
28fd0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ed.** [SQLITE_DO
28fe0 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  NE] from [sqlite
28ff0 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a  3_step(S)]) nor.
29000 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
29010 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
29020 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
29030 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
29040 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
29050 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
29060 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
29070 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
29080 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
29090 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
290a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
290b0 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
290c0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
290d0 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
290e0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
290f0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
29100 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
29110 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
29120 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
29130 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
29140 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
29150 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
29160 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
29170 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
29180 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
29190 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
291a0 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
291b0 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
291c0 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
291d0 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
291e0 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
291f0 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
29200 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
29210 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
29220 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
29230 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
29240 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
29250 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
29260 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
29270 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29280 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
29290 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
292a0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
292b0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
292c0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
292d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
292e0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
292f0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
29300 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29310 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
29320 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
29330 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
29340 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
29350 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
29360 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
29370 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
29380 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
29390 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
293a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
293b0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
293c0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
293d0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
293e0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
293f0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
29400 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
29410 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
29420 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
29430 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
29440 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
29450 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
29460 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29470 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
29480 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
29490 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
294a0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
294b0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
294c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
294d0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
294e0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
294f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
29500 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
29510 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
29520 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
29530 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29540 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
29550 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29560 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
29570 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
29580 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
29590 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
295a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
295b0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
295c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
295d0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
295e0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
295f0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
29600 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
29610 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
29620 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
29630 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
29640 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
29650 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
29660 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
29670 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
29680 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
29690 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
296a0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
296b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
296c0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
296d0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
296e0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
296f0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
29700 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
29710 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
29720 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
29730 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
29740 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
29750 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
29760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
29770 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
29780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
29790 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
297a0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
297b0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
297c0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
297d0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
297e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
297f0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
29800 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
29810 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
29820 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
29830 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
29840 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
29850 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
29860 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
29870 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
29880 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
29890 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
298a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
298b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
298c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
298d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
298e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
298f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29900 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
29910 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
29920 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
29930 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
29940 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
29950 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29960 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
29970 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
29980 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29990 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
299a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
299b0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
299c0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
299d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
299e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
299f0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
29a00 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
29a10 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
29a20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
29a30 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
29a40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
29a50 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
29a60 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
29a70 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
29a80 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
29a90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29aa0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
29ab0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
29ac0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
29ad0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
29ae0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
29af0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
29b00 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
29b10 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
29b20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
29b30 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
29b40 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
29b50 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
29b60 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
29b70 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
29b80 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
29b90 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
29ba0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
29bb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
29bc0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
29bd0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
29be0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29bf0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
29c00 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
29c10 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
29c20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
29c30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
29c40 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
29c50 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
29c60 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
29c70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
29c80 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
29c90 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
29ca0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
29cb0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
29cc0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
29cd0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
29ce0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
29cf0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
29d00 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
29d10 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
29d20 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
29d30 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
29d40 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
29d50 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
29d60 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
29d70 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
29d80 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
29d90 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
29da0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
29db0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
29dc0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
29dd0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
29de0 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f  inding}.** METHO
29df0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
29e00 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
29e10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
29e20 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
29e30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29e40 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
29e50 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
29e60 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
29e70 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
29e80 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
29e90 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
29ea0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
29eb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
29ec0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
29ed0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
29ee0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
29ef0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
29f00 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
29f10 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
29f20 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
29f30 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
29f40 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
29f50 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
29f60 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
29f70 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
29f80 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
29f90 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
29fa0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
29fb0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
29fc0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
29fd0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
29fe0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
29ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2a000 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
2a010 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
2a020 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2a030 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
2a040 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2a050 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
2a060 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2a070 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2a080 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
2a090 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
2a0a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a0b0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
2a0c0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2a0d0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2a0e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
2a0f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
2a100 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
2a110 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
2a120 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2a130 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
2a140 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
2a150 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
2a160 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
2a170 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
2a180 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
2a190 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
2a1a0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
2a1b0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
2a1c0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
2a1d0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
2a1e0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
2a1f0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
2a200 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
2a210 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a220 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
2a230 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
2a240 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
2a250 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
2a260 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2a270 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
2a280 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
2a290 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
2a2a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2a2b0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
2a2c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2a2d0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
2a2e0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
2a2f0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
2a300 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2a310 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
2a320 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
2a330 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
2a340 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2a350 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2a360 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2a370 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2a380 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2a390 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
2a3a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
2a3b0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
2a3c0 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
2a3d0 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
2a3e0 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
2a3f0 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
2a400 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
2a410 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
2a420 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
2a430 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
2a440 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
2a450 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2a460 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
2a470 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
2a480 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
2a490 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2a4a0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
2a4b0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
2a4c0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2a4d0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
2a4e0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
2a4f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2a500 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a510 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a520 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
2a530 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2a540 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
2a550 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
2a560 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a570 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
2a580 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2a590 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
2a5a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a5b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a5c0 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
2a5d0 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
2a5e0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2a5f0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
2a600 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
2a610 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2a620 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
2a630 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
2a640 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2a650 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73  nd_text16() or s
2a660 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a670 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61  64() then.** tha
2a680 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2a690 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
2a6a0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
2a6b0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
2a6c0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
2a6d0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
2a6e0 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
2a6f0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
2a700 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
2a710 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
2a720 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
2a730 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
2a740 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a750 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
2a760 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
2a770 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
2a780 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
2a790 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
2a7a0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
2a7b0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
2a7c0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
2a7d0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
2a7e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2a7f0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
2a800 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73  o the BLOB and s
2a810 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e  tring binding in
2a820 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61  terfaces.** is a
2a830 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
2a840 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2a850 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
2a860 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
2a870 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
2a880 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
2a890 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2a8a0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
2a8b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
2a8c0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
2a8d0 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20  he call to bind 
2a8e0 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49  API fails..** ^I
2a8f0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2a900 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
2a910 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
2a920 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
2a930 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
2a940 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
2a950 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
2a960 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
2a970 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
2a980 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2a990 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
2a9a0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2a9b0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
2a9c0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2a9d0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
2a9e0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
2a9f0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2aa00 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
2aa10 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
2aa20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2aa30 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
2aa40 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2aa50 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2aa60 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2aa70 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65  text64() must be
2aa80 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49   one of.** [SQLI
2aa90 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2aaa0 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
2aab0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
2aac0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a  SQLITE_UTF16LE].
2aad0 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ** to specify th
2aae0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  e encoding of th
2aaf0 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68  e text in the th
2ab00 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
2ab10 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20  If.** the sixth 
2ab20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2ab30 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2ab40 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
2ab50 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76  the.** allowed v
2ab60 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76  alues shown abov
2ab70 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78  e, or if the tex
2ab80 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  t encoding is di
2ab90 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20  fferent.** from 
2aba0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
2abb0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69  cified by the si
2abc0 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74  xth parameter, t
2abd0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2abe0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2abf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ac00 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2ac10 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
2ac20 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
2ac30 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
2ac40 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
2ac50 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
2ac60 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
2ac70 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
2ac80 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
2ac90 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
2aca0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
2acb0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
2acc0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
2acd0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
2ace0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
2acf0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
2ad00 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
2ad10 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
2ad20 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2ad30 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
2ad40 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
2ad50 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
2ad60 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
2ad70 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
2ad80 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
2ad90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2ada0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
2adb0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2adc0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2add0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2ade0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2adf0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2ae00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ae10 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2ae20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ae30 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2ae40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2ae50 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2ae60 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2ae70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ae80 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2ae90 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2aea0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2aeb0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2aec0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2aed0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2aee0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2aef0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2af00 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2af10 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2af20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2af30 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2af40 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2af50 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2af60 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2af70 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2af80 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2af90 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2afa0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2afb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2afc0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2afd0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2afe0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2aff0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2b000 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2b010 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2b020 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2b030 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2b040 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2b050 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2b060 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2b070 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2b080 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2b090 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2b0a0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2b0b0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2b0c0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2b0d0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2b0e0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2b0f0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2b100 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2b110 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2b120 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2b130 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2b140 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2b150 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b160 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2b170 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b180 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2b190 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2b1a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b1b0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2b1c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b1d0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2b1e0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2b1f0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
2b200 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2b210 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2b220 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2b230 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b240 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
2b250 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2b260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2b270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b280 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b290 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2b2a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
2b2b0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
2b2c0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2b2d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2b2e0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2b2f0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
2b300 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2b310 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
2b320 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b330 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2b340 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
2b350 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2b360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b370 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
2b380 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2b390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b3a0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2b3b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b3c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2b3d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2b3e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2b3f0 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
2b400 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b410 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2b420 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2b430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b440 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2b450 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
2b460 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74  r encoding);.int
2b470 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
2b480 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2b490 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
2b4a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2b4b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b4c0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
2b4d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2b4e0 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33   n);.int sqlite3
2b4f0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34  _bind_zeroblob64
2b500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b510 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  int, sqlite3_uin
2b520 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
2b530 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2b540 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
2b550 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2b560 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2b570 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2b580 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
2b590 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
2b5a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
2b5b0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
2b5c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
2b5d0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
2b5e0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
2b5f0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
2b600 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
2b610 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
2b620 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
2b630 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2b640 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
2b650 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b660 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
2b670 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
2b680 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
2b690 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
2b6a0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
2b6b0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
2b6c0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
2b6d0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
2b6e0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
2b6f0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
2b700 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
2b710 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
2b720 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
2b730 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
2b740 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
2b750 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
2b760 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
2b770 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
2b780 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
2b790 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2b7a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b7b0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2b7c0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2b7d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2b7e0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
2b7f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b800 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2b810 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b820 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2b830 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2b840 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2b850 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
2b860 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
2b870 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b880 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b890 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2b8a0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
2b8b0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
2b8c0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
2b8d0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
2b8e0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
2b8f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b900 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2b910 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
2b920 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
2b930 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2b940 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2b950 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
2b960 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
2b970 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
2b980 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2b990 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
2b9a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
2b9b0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
2b9c0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
2b9d0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
2b9e0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
2b9f0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
2ba00 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
2ba10 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2ba20 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
2ba30 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
2ba40 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
2ba50 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
2ba60 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
2ba70 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
2ba80 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
2ba90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2baa0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
2bab0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2bac0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
2bad0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
2bae0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
2baf0 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
2bb00 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
2bb10 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
2bb20 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
2bb30 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2bb40 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
2bb50 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
2bb60 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
2bb70 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2bb80 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
2bb90 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
2bba0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
2bbb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2bbc0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
2bbd0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2bbe0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2bbf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2bc00 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2bc10 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2bc20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2bc30 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2bc40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2bc50 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2bc60 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2bc70 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
2bc80 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
2bc90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2bca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bcb0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
2bcc0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
2bcd0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54  iven Name.** MET
2bce0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2bcf0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2bd00 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2bd10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2bd20 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2bd30 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2bd40 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2bd50 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2bd60 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2bd70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2bd80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2bd90 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2bda0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2bdb0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2bdc0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2bdd0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2bde0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2bdf0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2be00 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2be10 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2be20 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2be30 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2be40 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2be50 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2be60 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2be70 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2be80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2be90 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2bea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2beb0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2bec0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2bed0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bee0 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a  ter_name()]..*/.
2bef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2bf00 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2bf10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2bf20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2bf30 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2bf40 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2bf50 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2bf60 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2bf70 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2bf80 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43  e3_stmt.**.** ^C
2bf90 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
2bfa0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
2bfb0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
2bfc0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
2bfd0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
2bfe0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2bff0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
2c000 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c010 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
2c020 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
2c030 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
2c040 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
2c050 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
2c060 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2c070 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2c080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2c090 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2c0a0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2c0b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2c0c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2c0d0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2c0e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2c0f0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2c100 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2c110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c120 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2c130 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2c140 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2c150 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2c160 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2c170 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2c180 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2c190 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2c1a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2c1b0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2c1c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2c1d0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2c1e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2c1f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2c200 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2c210 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2c220 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2c230 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2c240 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c250 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
2c260 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
2c270 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
2c280 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2c290 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2c2a0 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
2c2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2c2c0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2c2d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2c2e0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2c2f0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2c300 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
2c310 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2c320 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
2c330 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2c340 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
2c350 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2c360 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2c370 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
2c380 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c390 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2c3a0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2c3b0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
2c3c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2c3d0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
2c3e0 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
2c3f0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
2c400 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
2c410 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2c420 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
2c430 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
2c440 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
2c450 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2c460 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
2c470 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c480 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2c490 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c4a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2c4b0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2c4c0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2c4d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c4e0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2c4f0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2c500 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
2c510 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2c520 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
2c530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c540 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
2c550 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
2c560 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
2c570 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
2c580 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
2c590 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
2c5a0 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
2c5b0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
2c5c0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
2c5d0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
2c5e0 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
2c5f0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2c600 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2c610 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
2c620 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
2c630 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
2c640 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
2c650 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
2c660 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
2c670 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
2c680 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
2c690 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
2c6a0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
2c6b0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
2c6c0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
2c6d0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
2c6e0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
2c6f0 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
2c700 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c710 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2c720 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
2c730 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2c740 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2c750 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c760 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
2c770 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
2c780 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
2c790 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
2c7a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c7b0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2c7c0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2c7d0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2c7e0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2c7f0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2c800 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2c810 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2c820 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2c830 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2c840 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2c850 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2c860 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2c870 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2c880 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2c890 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2c8a0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2c8b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2c8c0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2c8d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c8e0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2c8f0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2c900 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2c910 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2c920 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2c930 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2c940 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2c950 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2c960 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2c970 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2c980 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c990 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2c9a0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2c9b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c9c0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2c9d0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2c9e0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2c9f0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2ca00 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2ca10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2ca20 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2ca30 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2ca40 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2ca50 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2ca60 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2ca70 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2ca80 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2ca90 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2caa0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2cab0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2cac0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2cad0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2cae0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2caf0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2cb00 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2cb10 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2cb20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2cb30 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2cb40 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2cb50 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2cb60 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2cb70 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2cb80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2cb90 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2cba0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2cbb0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2cbc0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2cbd0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2cbe0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2cbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cc00 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2cc10 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2cc20 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2cc30 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2cc40 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2cc50 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2cc60 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2cc70 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2cc80 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2cc90 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2cca0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2ccb0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2ccc0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2ccd0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2cce0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2ccf0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2cd00 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2cd10 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2cd20 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2cd30 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2cd40 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2cd50 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2cd60 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2cd70 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2cd80 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2cd90 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2cda0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2cdb0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2cdc0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2cdd0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2cde0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2cdf0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2ce00 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2ce10 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2ce20 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2ce30 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2ce40 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2ce50 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2ce60 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2ce70 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2ce80 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2ce90 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2cea0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2ceb0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2cec0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ced0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2cee0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2cef0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2cf00 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2cf10 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2cf20 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2cf30 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2cf40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2cf50 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2cf60 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2cf70 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2cf80 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2cf90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cfa0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2cfb0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2cfc0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2cfd0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2cfe0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2cff0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d000 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2d010 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2d020 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2d030 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2d040 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2d050 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d060 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2d070 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d080 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2d090 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d0a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2d0b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2d0c0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2d0d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2d0e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2d0f0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2d100 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2d110 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2d120 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2d130 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2d140 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d150 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d160 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2d170 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2d180 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2d190 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d1a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2d1b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2d1c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d1d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2d1e0 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2d1f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2d200 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2d210 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2d220 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2d230 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2d240 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2d250 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2d260 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2d270 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2d280 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2d290 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2d2a0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2d2b0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2d2c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2d2d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2d2e0 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2d2f0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2d300 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2d310 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2d320 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2d330 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2d340 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2d350 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2d360 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2d370 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2d380 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2d390 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2d3a0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2d3b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2d3c0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2d3d0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2d3e0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2d3f0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2d400 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2d410 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2d420 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2d430 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2d440 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2d450 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2d460 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2d470 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2d480 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2d490 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2d4a0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2d4b0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2d4c0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2d4d0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2d4e0 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2d4f0 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2d500 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2d510 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2d520 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2d530 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2d540 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2d550 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2d560 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2d570 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2d580 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2d590 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2d5a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2d5b0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2d5c0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2d5d0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2d5e0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2d5f0 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73   values..*/.cons
2d600 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2d610 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2d620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d630 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2d640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d650 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
2d660 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2d670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2d680 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
2d690 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
2d6a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d6b0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2d6c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d6d0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2d6e0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2d6f0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2d700 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2d710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d720 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2d730 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2d740 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2d750 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2d760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2d770 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2d780 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2d790 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2d7a0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2d7b0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2d7c0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2d7d0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2d7e0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2d7f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2d800 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2d810 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2d820 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2d830 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2d840 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2d850 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2d860 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d870 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2d880 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2d890 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2d8a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2d8b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d8c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d8d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2d8e0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2d8f0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2d900 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2d910 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2d920 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2d930 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2d940 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2d950 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2d960 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2d970 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2d980 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2d990 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2d9a0 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2d9b0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2d9c0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2d9d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2d9e0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2d9f0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2da00 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2da10 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2da20 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2da30 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2da40 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2da50 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2da60 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2da70 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2da80 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2da90 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2daa0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2dab0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2dac0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2dad0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2dae0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2daf0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2db00 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2db10 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2db20 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2db30 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2db40 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2db50 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2db60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2db70 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2db80 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2db90 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2dba0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2dbb0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2dbc0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2dbd0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2dbe0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2dbf0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2dc00 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2dc10 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2dc20 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2dc30 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2dc40 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2dc50 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2dc60 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2dc70 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2dc80 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2dc90 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2dca0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2dcb0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2dcc0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2dcd0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2dce0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2dcf0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2dd00 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2dd10 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2dd20 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2dd30 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2dd40 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2dd50 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2dd60 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2dd70 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2dd80 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2dd90 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2dda0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2ddb0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2ddc0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2ddd0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2dde0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2ddf0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2de00 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2de10 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2de20 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2de30 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2de40 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2de50 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2de60 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2de70 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2de80 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2de90 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2dea0 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2deb0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2dec0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2ded0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2dee0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2def0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2df00 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2df10 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2df20 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2df30 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2df40 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2df50 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2df60 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2df70 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2df80 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2df90 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2dfa0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2dfb0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2dfc0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2dfd0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2dfe0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2dff0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2e000 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2e010 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2e020 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2e030 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2e040 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2e050 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2e060 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2e070 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2e080 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2e090 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2e0a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2e0b0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2e0c0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2e0d0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e0e0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2e0f0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2e100 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2e110 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2e120 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2e130 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2e140 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2e150 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2e160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e170 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2e180 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2e190 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2e1a0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2e1b0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2e1c0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2e1d0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2e1e0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2e1f0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2e200 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e210 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2e220 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2e230 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2e240 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2e250 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2e260 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2e270 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2e280 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2e290 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2e2a0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2e2b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e2c0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2e2d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2e2e0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2e2f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2e300 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2e310 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2e320 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2e330 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2e340 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2e350 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2e360 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2e370 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2e380 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2e390 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2e3a0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2e3b0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2e3c0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2e3d0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2e3e0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2e3f0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2e400 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2e410 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2e420 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2e430 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2e440 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2e450 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2e460 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2e470 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2e480 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2e490 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2e4a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2e4b0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2e4c0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2e4d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2e4e0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2e4f0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2e500 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2e510 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2e520 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2e530 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2e540 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2e550 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e560 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2e570 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2e580 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2e590 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2e5a0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2e5b0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2e5c0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2e5d0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2e5e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2e5f0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2e600 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2e610 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2e620 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2e630 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2e640 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2e650 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2e660 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2e670 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2e680 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2e690 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2e6a0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2e6b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e6c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2e6d0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2e6e0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2e6f0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2e700 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2e710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e720 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2e730 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2e740 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2e750 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2e760 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2e770 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2e780 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2e790 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2e7a0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2e7b0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2e7c0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2e7d0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2e7e0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2e7f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2e800 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
2e810 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e820 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2e830 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e840 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2e850 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2e860 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2e870 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
2e880 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2e890 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
2e8a0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2e8b0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
2e8c0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
2e8d0 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
2e8e0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
2e8f0 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
2e900 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2e910 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
2e920 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
2e930 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
2e940 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
2e950 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
2e960 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
2e970 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2e980 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
2e990 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
2e9a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e9b0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
2e9c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2e9d0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2e9e0 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
2e9f0 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
2ea00 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2ea10 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2ea20 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
2ea30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2ea40 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
2ea50 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
2ea60 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2ea70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2ea80 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
2ea90 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
2eaa0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
2eab0 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
2eac0 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
2ead0 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
2eae0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
2eaf0 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
2eb00 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
2eb10 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
2eb20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
2eb30 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
2eb40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2eb50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2eb60 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
2eb70 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2eb80 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2eb90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2eba0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2ebb0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2ebc0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2ebd0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2ebe0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2ebf0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2ec00 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2ec10 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2ec20 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2ec30 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2ec40 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2ec50 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2ec60 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2ec70 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2ec80 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2ec90 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2eca0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2ecb0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2ecc0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2ecd0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2ece0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2ecf0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2ed00 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2ed10 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2ed20 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2ed30 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2ed40 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2ed50 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2ed60 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2ed70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2ed80 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2ed90 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2eda0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2edb0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2edc0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2edd0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2ede0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2edf0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2ee00 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2ee10 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2ee20 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2ee30 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2ee40 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2ee50 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2ee60 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2ee70 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2ee80 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2ee90 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2eea0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2eeb0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2eec0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2eed0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2eee0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
2eef0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2ef00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2ef10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2ef20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2ef30 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2ef40 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2ef50 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2ef60 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2ef70 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2ef80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2ef90 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2efa0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2efb0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2efc0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2efd0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2efe0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2eff0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2f000 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f010 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2f020 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2f030 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2f040 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2f050 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2f060 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2f070 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2f080 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2f090 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2f0a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2f0b0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2f0c0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2f0d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2f0e0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2f0f0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2f100 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2f110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2f120 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2f130 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2f140 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2f150 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2f160 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2f170 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2f180 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2f190 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2f1a0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2f1b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2f1c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2f1d0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2f1e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2f1f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2f200 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2f210 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2f220 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2f230 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f240 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2f250 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2f260 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2f270 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2f280 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2f290 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2f2a0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2f2b0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2f2c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f2d0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2f2e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2f2f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2f300 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2f310 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2f320 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2f330 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2f340 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f350 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2f360 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2f370 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2f380 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2f390 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2f3a0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2f3b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2f3c0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2f3d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2f3e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2f3f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f400 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2f410 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2f420 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2f430 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2f440 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2f450 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2f460 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2f470 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2f480 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2f490 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2f4a0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2f4b0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2f4c0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2f4d0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2f4e0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2f4f0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2f500 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2f510 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2f520 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2f530 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2f540 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2f550 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2f560 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2f570 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2f580 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2f590 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2f5a0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2f5b0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2f5c0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2f5d0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2f5e0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2f5f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2f600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f610 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2f620 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2f630 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2f640 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f650 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2f660 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2f670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f680 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2f690 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2f6a0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2f6b0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2f6c0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2f6d0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2f6e0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2f6f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f700 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2f710 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2f720 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2f730 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2f740 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2f750 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f760 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2f770 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2f780 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2f790 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2f7a0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2f7b0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2f7c0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2f7d0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2f7e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2f7f0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2f800 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2f810 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2f820 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2f830 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2f840 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2f850 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2f860 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2f870 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2f880 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2f890 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2f8a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2f8b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f8c0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2f8d0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2f8e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f8f0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2f900 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2f910 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2f920 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2f930 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2f940 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2f950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2f960 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2f970 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2f980 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2f990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f9a0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2f9b0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2f9c0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2f9d0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2f9e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2f9f0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2fa00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2fa10 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2fa20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fa30 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2fa40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa50 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2fa60 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2fa70 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2fa80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2fa90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2faa0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2fab0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2fac0 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2fad0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2fae0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2faf0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2fb00 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2fb10 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2fb20 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2fb30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fb40 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2fb50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2fb60 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2fb70 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2fb80 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2fb90 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2fba0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2fbb0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2fbc0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2fbd0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2fbe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fbf0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2fc00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2fc10 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2fc20 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2fc30 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2fc40 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2fc50 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2fc60 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2fc70 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2fc80 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
2fc90 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
2fca0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2fcb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2fcc0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2fcd0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2fce0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2fcf0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
2fd00 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
2fd10 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
2fd20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2fd30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2fd40 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
2fd50 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
2fd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2fd70 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2fd80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2fd90 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2fda0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2fdb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2fdc0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2fdd0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2fde0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2fdf0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2fe00 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2fe10 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2fe20 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2fe30 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2fe40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2fe50 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2fe60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fe70 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
2fe80 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
2fe90 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20  readsafe..**.** 
2fea0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2feb0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2fec0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2fed0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2fee0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2fef0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2ff00 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2ff10 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2ff20 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2ff30 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2ff40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2ff50 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2ff60 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2ff70 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2ff80 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2ff90 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2ffa0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2ffb0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2ffc0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2ffd0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2ffe0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2fff0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
30000 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
30010 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
30020 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
30030 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
30040 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
30050 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
30060 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
30070 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
30080 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
30090 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
300a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
300b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
300c0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
300d0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
300e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
300f0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
30100 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
30110 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
30120 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
30130 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
30140 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
30150 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
30160 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
30170 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
30180 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
30190 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
301a0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
301b0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
301c0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
301d0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
301e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
301f0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
30200 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
30210 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
30220 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
30230 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
30240 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
30250 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
30260 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
30270 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
30280 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
30290 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
302a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
302b0 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
302c0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
302d0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
302e0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
302f0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
30300 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
30310 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
30320 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
30330 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
30340 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
30350 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
30360 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
30370 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
30380 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
30390 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
303a0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
303b0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
303c0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
303d0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
303e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
303f0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
30400 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
30410 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
30420 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
30430 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
30440 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
30450 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
30460 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
30470 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
30480 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
30490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
304a0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
304b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
304c0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
304d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
304e0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
304f0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
30500 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
30510 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
30520 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
30530 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
30540 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
30550 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
30560 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
30570 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
30580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30590 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
305a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
305b0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
305c0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
305d0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
305e0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
305f0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
30600 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
30610 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
30620 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
30630 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
30640 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
30650 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30660 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30670 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
30680 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
30690 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
306a0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
306b0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
306c0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
306d0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
306e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
306f0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
30700 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
30710 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
30720 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
30730 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
30740 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
30750 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
30760 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
30770 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
30780 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
30790 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
307a0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
307b0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
307c0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
307d0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
307e0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
307f0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
30800 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
30810 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
30820 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
30830 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
30840 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
30850 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
30860 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
30870 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
30880 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
30890 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
308a0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
308b0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
308c0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
308d0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
308e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
308f0 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  st policy is to 
30900 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
30910 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
30920 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
30930 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
30940 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
30950 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30960 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
30970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30980 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
30990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
309a0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
309b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
309c0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
309d0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
309e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
309f0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
30a00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30a10 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
30a20 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
30a30 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
30a40 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
30a50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
30a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30a70 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
30a80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30a90 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
30aa0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
30ab0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
30ac0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
30ad0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
30ae0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
30af0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
30b00 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
30b10 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
30b20 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
30b30 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
30b40 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
30b50 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
30b60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30b70 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
30b80 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30b90 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
30ba0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
30bb0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
30bc0 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
30bd0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
30be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30bf0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
30c00 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
30c10 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
30c20 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
30c30 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
30c40 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
30c50 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
30c60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
30c70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30c80 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
30c90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
30ca0 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
30cb0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
30cc0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
30cd0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
30ce0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
30cf0 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74  lly.  Do <em>not
30d00 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70  </em> pass the p
30d10 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
30d20 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
30d30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
30d40 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
30d50 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
30d60 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
30d70 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
30d80 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
30d90 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
30da0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
30db0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
30dc0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
30dd0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
30de0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
30df0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
30e00 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
30e10 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
30e20 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
30e30 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
30e40 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
30e50 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
30e60 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
30e70 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
30e80 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
30e90 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
30ea0 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
30eb0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30ec0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
30ed0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30ee0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
30ef0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
30f00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30f10 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
30f20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
30f30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30f40 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
30f50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
30f60 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
30f70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30f80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
30f90 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
30fa0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30fb0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
30fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
30fd0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
30fe0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
30ff0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
31000 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
31010 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
31020 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31030 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31050 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
31060 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
31070 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31080 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
31090 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
310a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
310b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
310c0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
310d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
310e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
310f0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
31100 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
31110 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  t.** DESTRUCTOR:
31120 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31130 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31140 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
31150 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
31160 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
31170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
31180 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
31190 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
311a0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
311b0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
311c0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
311d0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
311e0 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
311f0 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
31200 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31210 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
31220 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
31230 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
31240 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
31250 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
31260 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
31270 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
31280 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
31290 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
312a0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
312b0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
312c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
312d0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
312e0 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
312f0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
31300 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
31310 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
31320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31330 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
31340 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
31350 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
31360 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
31370 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
31380 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
31390 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
313a0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
313b0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
313c0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
313d0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
313e0 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
313f0 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
31400 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
31410 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
31420 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
31430 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
31440 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
31450 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
31460 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
31470 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31480 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
31490 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
314a0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
314b0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
314c0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
314d0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
314e0 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
314f0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
31500 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
31510 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
31520 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
31530 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
31540 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
31550 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
31560 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
31570 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
31580 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
31590 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
315a0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
315b0 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
315c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
315d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
315e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
315f0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
31600 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
31610 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  bject.** METHOD:
31620 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31630 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31640 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
31650 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
31660 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
31670 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
31680 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
31690 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
316a0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
316b0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
316c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
316d0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
316e0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
316f0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
31700 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
31710 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
31720 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
31730 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
31740 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
31750 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
31760 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
31770 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
31780 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
31790 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
317a0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
317b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
317c0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
317d0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
317e0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
317f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
31800 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
31810 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31820 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
31830 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31840 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
31850 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
31860 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
31870 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
31880 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
31890 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
318a0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
318b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
318c0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
318d0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
318e0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
318f0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
31900 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
31910 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
31920 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31930 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
31940 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
31950 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
31960 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
31970 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
31980 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
31990 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
319a0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
319b0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
319c0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
319d0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
319e0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
319f0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
31a00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
31a10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
31a20 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
31a30 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
31a40 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
31a50 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
31a60 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
31a70 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
31a80 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
31a90 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
31aa0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
31ab0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31ac0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
31ad0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
31ae0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31af0 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
31b00 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
31b10 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
31b20 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
31b30 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
31b40 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
31b50 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
31b60 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
31b70 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
31b80 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
31b90 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
31ba0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
31bb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
31bc0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
31bd0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
31be0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
31bf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
31c00 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
31c10 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
31c20 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
31c30 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
31c40 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
31c50 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
31c60 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
31c70 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
31c80 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
31c90 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
31ca0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31cb0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
31cc0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
31cd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
31ce0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31cf0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
31d00 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
31d10 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
31d20 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
31d30 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
31d40 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
31d50 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
31d60 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
31d70 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
31d80 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
31d90 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
31da0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31db0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
31dc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
31dd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
31de0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31df0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
31e00 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
31e10 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
31e20 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
31e30 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
31e40 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
31e50 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
31e60 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
31e70 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
31e80 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
31e90 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
31ea0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
31eb0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
31ec0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
31ed0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
31ee0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
31ef0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
31f00 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
31f10 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
31f20 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
31f30 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
31f40 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
31f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
31f60 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
31f70 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
31f80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
31f90 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
31fa0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
31fb0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
31fc0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
31fd0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
31fe0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
31ff0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
32000 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
32010 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
32020 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
32030 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
32040 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
32050 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
32060 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
32070 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
32080 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
32090 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
320a0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
320b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
320c0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
320d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
320e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
320f0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
32100 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
32110 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
32120 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
32130 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
32140 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
32150 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
32160 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
32170 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
32180 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
32190 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
321a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
321b0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
321c0 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
321d0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
321e0 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
321f0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
32200 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
32210 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
32220 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
32230 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
32240 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
32250 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
32260 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
32270 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
32280 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
32290 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
322a0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
322b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
322c0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
322d0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
322e0 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
322f0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
32300 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
32310 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
32320 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
32330 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
32340 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
32350 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32360 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
32370 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
32380 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
32390 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
323a0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
323b0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
323c0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
323d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
323e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
323f0 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
32400 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
32410 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
32420 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
32430 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
32440 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
32450 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
32460 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
32470 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
32480 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
32490 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
324a0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
324b0 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
324c0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
324d0 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
324e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
324f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
32500 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
32510 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
32520 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
32530 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
32540 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
32550 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
32560 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
32570 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
32580 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
32590 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
325a0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
325b0 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
325c0 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
325d0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
325e0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
325f0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
32600 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
32610 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32620 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
32630 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
32640 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
32650 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
32660 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
32670 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
32680 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
32690 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
326a0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
326b0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
326c0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
326d0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
326e0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
326f0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
32700 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
32710 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
32720 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
32730 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
32740 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
32750 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
32760 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
32770 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
32780 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
32790 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
327a0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
327b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
327c0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
327d0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
327e0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
327f0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
32800 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
32810 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
32820 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
32830 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
32840 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
32850 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
32860 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
32870 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
32880 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
32890 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
328a0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
328b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
328c0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
328d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
328e0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
328f0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
32900 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
32910 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
32920 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
32930 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
32940 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
32950 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
32960 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
32970 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
32980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32990 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
329a0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
329b0 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
329c0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
329d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
329e0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
329f0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
32a00 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
32a10 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
32a20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
32a30 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
32a40 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
32a50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
32a60 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
32a70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
32a80 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
32a90 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
32aa0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
32ab0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32ac0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
32ad0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
32ae0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
32af0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
32b00 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
32b10 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
32b20 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
32b30 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
32b40 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
32b50 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
32b60 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
32b70 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
32b80 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
32b90 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
32ba0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
32bb0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
32bc0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
32bd0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
32be0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
32bf0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
32c00 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
32c10 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
32c20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
32c30 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
32c40 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
32c50 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
32c60 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
32c70 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
32c80 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
32c90 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
32ca0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
32cb0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
32cc0 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
32cd0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
32ce0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
32cf0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
32d00 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
32d10 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
32d20 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
32d30 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
32d40 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
32d50 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
32d60 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
32d70 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
32d80 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
32d90 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
32da0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
32db0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
32dc0 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
32dd0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
32de0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
32df0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
32e00 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
32e10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
32e20 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
32e30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32e40 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
32e50 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
32e60 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
32e70 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
32e80 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
32e90 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
32ea0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
32eb0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
32ec0 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
32ed0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
32ee0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
32ef0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
32f00 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
32f10 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
32f20 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
32f30 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
32f40 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
32f50 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
32f60 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
32f70 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
32f80 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
32f90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32fa0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32fb0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32fc0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
32fd0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32fe0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32ff0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
33000 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33010 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
33020 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33030 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
33040 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
33050 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
33060 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
33070 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
33080 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
33090 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
330a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
330b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
330c0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
330d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
330e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
330f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
33100 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
33110 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
33120 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
33130 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
33140 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
33150 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
33160 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
33170 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
33180 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
33190 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
331a0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
331b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
331c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
331d0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
331e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
331f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33200 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
33210 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
33220 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
33230 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
33240 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33250 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
33260 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
33270 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
33280 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
33290 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
332a0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
332b0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
332c0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
332d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
332e0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
332f0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37      /* IMP: R-37
33300 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65  514-35566 */.#de
33310 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
33320 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20  6LE        2    
33330 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d  /* IMP: R-03371-
33340 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65  37637 */.#define
33350 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
33360 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49         3    /* I
33370 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35  MP: R-51971-3415
33380 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
33390 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
333a0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
333b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
333c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
333d0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
333e0 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63    5    /* Deprec
333f0 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ated */.#define 
33400 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
33410 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
33420 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33430 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
33440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33450 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a  Function Flags.*
33460 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
33470 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64  ants may be ORed
33480 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74   together with t
33490 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  he .** [SQLITE_U
334a0 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20  TF8 | preferred 
334b0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61  text encoding] a
334c0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
334d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
334e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
334f0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
33500 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33510 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
33520 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33530 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  nction_v2()]..*/
33540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33550 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20  DETERMINISTIC   
33560 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41   0x800../*.** CA
33570 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
33580 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
33590 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
335a0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
335b0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
335c0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
335d0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
335e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
335f0 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
33600 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
33610 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
33620 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
33630 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
33640 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
33650 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
33660 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
33670 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e  unctions.  To en
33680 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d  courage programm
33690 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ers to avoid.** 
336a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
336b0 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70   we will not exp
336c0 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64  lain what they d
336d0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
336e0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
336f0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
33700 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
33710 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
33720 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
33730 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
33740 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
33750 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
33760 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
33770 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
33780 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
33790 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
337a0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
337b0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
337c0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
337d0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
337e0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
337f0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
33800 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
33810 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
33820 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
33830 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
33840 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
33850 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
33860 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
33870 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
33880 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
33890 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
338a0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
338b0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
338c0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
338d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
338e0 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  ue.**.** The C-l
338f0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
33900 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
33910 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
33920 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
33930 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
33940 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
33950 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
33960 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
33970 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
33980 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a  or aggregate.  .
33990 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
339a0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
339b0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
339c0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
339d0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
339e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
339f0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
33a00 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
33a10 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
33a20 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
33a30 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
33a40 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
33a50 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
33a60 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
33a70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33a80 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
33a90 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
33aa0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
33ab0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33ac0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
33ad0 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
33ae0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33af0 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
33b00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33b10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
33b20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
33b30 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
33b40 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
33b50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
33b60 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
33b70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
33b80 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
33b90 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
33ba0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33bb0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
33bc0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
33bd0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
33be0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33bf0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
33c00 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
33c10 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
33c20 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
33c30 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
33c40 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
33c50 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
33c60 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33c70 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
33c80 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69  that these routi
33c90 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
33ca0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
33cb0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33cc0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
33cd0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
33ce0 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
33cf0 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
33d00 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
33d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33d20 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33d30 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
33d40 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
33d50 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
33d60 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
33d70 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
33d80 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
33d90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33da0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
33db0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33dc0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
33dd0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
33de0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
33df0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
33e00 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
33e10 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
33e20 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
33e30 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
33e40 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
33e50 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
33e60 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
33e70 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
33e80 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
33e90 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
33ea0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
33eb0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
33ec0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
33ed0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
33ee0 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
33ef0 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
33f00 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
33f10 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
33f20 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
33f30 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
33f40 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
33f50 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
33f60 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
33f70 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
33f80 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
33f90 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
33fa0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
33fb0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
33fc0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
33fd0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
33fe0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
33ff0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
34000 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
34010 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
34020 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
34030 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
34040 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
34050 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
34060 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
34070 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
34080 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
34090 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
340a0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
340b0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
340c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
340d0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
340e0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
340f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
34100 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
34110 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34120 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
34130 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
34140 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
34150 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
34160 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
34170 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
34180 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
34190 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
341a0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
341b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
341c0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
341d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
341e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
341f0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
34200 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
34210 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
34220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34230 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
34240 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
34250 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
34260 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
34270 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
34280 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
34290 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
342a0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
342b0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
342c0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
342d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
342e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
342f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34300 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34310 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
34320 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
34330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34340 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
34350 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
34360 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
34370 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
34380 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
34390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
343a0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
343b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
343c0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
343d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
343e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
343f0 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20  EF: Finding The 
34400 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56  Subtype Of SQL V
34410 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
34420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
34430 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34440 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56  _value_subtype(V
34450 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
34460 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66  ns the subtype f
34470 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63  or.** an [applic
34480 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34490 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75  L function] argu
344a0 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62  ment V.  The sub
344b0 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  type.** informat
344c0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
344d0 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65  to pass a limite
344e0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  d amount of cont
344f0 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  ext from.** one 
34500 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
34510 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68  another.  Use th
34520 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
34530 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20  t_subtype()].** 
34540 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74  routine to set t
34550 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74  he subtype for t
34560 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
34570 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  of an SQL functi
34580 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
34590 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66   makes no use of
345a0 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e   subtype itself.
345b0 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73    It merely pass
345c0 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a  es the subtype.*
345d0 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c  * from the resul
345e0 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63  t of one [applic
345f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34600 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f  L function] into
34610 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66   the.** input of
34620 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73   another..*/.uns
34630 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65  igned int sqlite
34640 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28  3_value_subtype(
34650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34660 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34670 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20  : Copy And Free 
34680 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
34690 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
346a0 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  lue.**.** ^The s
346b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
346c0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  (V) interface ma
346d0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
346e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
346f0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e  ].** object D an
34700 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
34710 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79  ter to that copy
34720 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
34730 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64  _value] returned
34740 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63  .** is a [protec
34750 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34760 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69  e] object even i
34770 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e  f the input is n
34780 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ot..** ^The sqli
34790 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29  te3_value_dup(V)
347a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
347b0 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20  ns NULL if V is 
347c0 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20  NULL or if a.** 
347d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
347e0 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  n fails..**.** ^
347f0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
34800 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66  e_free(V) interf
34810 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71  ace frees an [sq
34820 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34830 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ect.** previousl
34840 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
34850 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
34860 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73  up()].  ^If V is
34870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
34880 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
34890 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73  value_free(V) is
348a0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
348b0 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61  p..*/.sqlite3_va
348c0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  lue *sqlite3_val
348d0 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c  ue_dup(const sql
348e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
348f0 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  id sqlite3_value
34900 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61  _free(sqlite3_va
34910 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
34920 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
34930 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
34940 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54  n Context.** MET
34950 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
34960 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
34970 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
34980 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
34990 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
349a0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
349b0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
349c0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
349d0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
349e0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
349f0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34a00 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
34a10 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
34a20 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
34a30 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
34a40 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
34a50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
34a60 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
34a70 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
34a80 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
34a90 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
34aa0 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
34ab0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
34ac0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
34ad0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
34ae0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
34af0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
34b00 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
34b10 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
34b20 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
34b30 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
34b40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34b50 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
34b60 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
34b70 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
34b80 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
34b90 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
34ba0 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
34bb0 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
34bc0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
34bd0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
34be0 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
34bf0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
34c00 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
34c10 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
34c20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
34c30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
34c40 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
34c50 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
34c60 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
34c70 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
34c80 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
34c90 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
34ca0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
34cb0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
34cc0 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
34cd0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
34ce0 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
34cf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
34d00 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34d10 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
34d20 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
34d30 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69  nter .** when fi
34d40 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20  rst called if N 
34d50 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
34d60 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
34d70 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
34d80 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
34d90 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
34da0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
34db0 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
34dc0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34dd0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
34de0 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
34df0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
34e00 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
34e10 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
34e20 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
34e30 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
34e40 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
34e50 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34e60 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
34e70 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
34e80 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
34e90 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
34ea0 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
34eb0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
34ec0 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68  on.)^  Within th
34ed0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
34ee0 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61  k, it is customa
34ef0 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30  ry to set.** N=0
34f00 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   in calls to sql
34f10 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34f20 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74  ontext(C,N) so t
34f30 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74  hat no .** point
34f40 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  less memory allo
34f50 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a  cations occur..*
34f60 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
34f70 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
34f80 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
34f90 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
34fa0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34fb0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
34fc0 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
34fd0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
34fe0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
34ff0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
35000 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
35010 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
35020 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
35030 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
35040 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
35050 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
35060 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
35070 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
35080 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
35090 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
350a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
350b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
350c0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
350d0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
350e0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
350f0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
35100 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
35110 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
35120 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35130 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
35140 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
35150 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
35160 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
35170 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
35180 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35190 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
351a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
351b0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
351c0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
351d0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
351e0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
351f0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
35200 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
35210 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
35220 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
35230 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
35240 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
35250 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
35260 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
35270 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
35280 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
35290 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
352a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
352b0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
352c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
352d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
352e0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
352f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35300 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35310 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
35320 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
35330 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
35340 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
35350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
35360 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
35370 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
35380 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
35390 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
353a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
353b0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
353c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
353d0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
353e0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
353f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35400 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
35410 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
35420 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
35430 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
35440 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
35450 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35460 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
35470 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
35480 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
35490 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
354a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
354b0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
354c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
354d0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
354e0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
354f0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
35500 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
35510 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ta.** METHOD: sq
35520 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
35530 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
35540 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
35550 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74  by (non-aggregat
35560 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  e) SQL functions
35570 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
35580 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
35590 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
355a0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
355b0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
355c0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
355d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
355e0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
355f0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
35600 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
35610 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
35620 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
35630 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
35640 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41  be preserved.  A
35650 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20  n example.** of 
35660 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74  where this might
35670 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e   be useful is in
35680 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
35690 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a  ssion matching.*
356a0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
356b0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
356c0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
356d0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
356e0 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  e stored as.** m
356f0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
35700 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74  ed with the patt
35710 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a  ern string.  .**
35720 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73   Then as long as
35730 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
35740 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20  ing remains the 
35750 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d  same,.** the com
35760 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
35770 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
35780 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
35790 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
357a0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
357b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nction..**.** ^T
357c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
357d0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
357e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
357f0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
35800 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
35810 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
35820 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
35830 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
35840 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
35850 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
35860 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35870 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
35880 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
35890 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
358a0 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e  ted with the fun
358b0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20  ction argument, 
358c0 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74  this sqlite3_get
358d0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
358e0 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
358f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35910 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
35920 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63  ,N,P,X) interfac
35930 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74  e saves P as met
35940 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
35950 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
35960 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35970 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35980 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74  on.  ^Subsequent
35990 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
359a0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
359b0 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66  (C,N) return P f
359c0 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63  rom the most rec
359d0 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ent.** sqlite3_s
359e0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
359f0 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20  ,X) call if the 
35a00 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c  metadata is stil
35a10 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55  l valid or.** NU
35a20 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  LL if the metada
35a30 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63  ta has been disc
35a40 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72  arded..** ^After
35a50 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   each call to sq
35a60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35a70 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65  a(C,N,P,X) where
35a80 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a   X is not NULL,.
35a90 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  ** SQLite will i
35aa0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
35ab0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20  ctor function X 
35ac0 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50  with parameter P
35ad0 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65   exactly.** once
35ae0 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64  , when the metad
35af0 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64  ata is discarded
35b00 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  ..** SQLite is f
35b10 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74  ree to discard t
35b20 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61  he metadata at a
35b30 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69  ny time, includi
35b40 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  ng: <ul>.** <li>
35b50 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
35b60 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
35b70 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
35b80 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77  es, or.** <li> w
35b90 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
35ba0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
35bb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
35bc0 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
35bd0 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74  **      SQL stat
35be0 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  ement, or.** <li
35bf0 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  > when sqlite3_s
35c00 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20  et_auxdata() is 
35c10 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e  invoked again on
35c20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65   the same parame
35c30 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ter, or.** <li> 
35c40 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69  during the origi
35c50 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  nal sqlite3_set_
35c60 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77  auxdata() call w
35c70 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a  hen a memory .**
35c80 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e        allocation
35c90 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c   error occurs. <
35ca0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  /ul>)^.**.** Not
35cb0 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65  e the last bulle
35cc0 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e  t in particular.
35cd0 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72    The destructor
35ce0 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65   X in .** sqlite
35cf0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
35d00 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20  N,P,X) might be 
35d10 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65  called immediate
35d20 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a  ly, before the.*
35d30 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
35d40 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
35d50 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20  e even returns. 
35d60 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73   Hence sqlite3_s
35d70 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20  et_auxdata().** 
35d80 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64  should be called
35d90 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66   near the end of
35da0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
35db0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  plementation and
35dc0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
35dd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35de0 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20  should not make 
35df0 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74  any use of P aft
35e00 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  er.** sqlite3_se
35e10 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20  t_auxdata() has 
35e20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a  been called..**.
35e30 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
35e40 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
35e50 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
35e60 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
35e70 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  or.** function p
35e80 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
35e90 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  re compile-time 
35ea0 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75  constants, inclu
35eb0 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  ding literal.** 
35ec0 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
35ed0 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72  meters] and expr
35ee0 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64  essions composed
35ef0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29   from the same.)
35f00 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
35f10 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
35f20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
35f30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
35f40 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
35f50 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
35f60 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
35f70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
35f80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35f90 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
35fa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35fb0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
35fc0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
35fd0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
35fe0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
35ff0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
36000 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
36010 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
36020 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
36030 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
36040 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
36050 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
36060 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
36070 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
36080 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
36090 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
360a0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
360b0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
360c0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
360d0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
360e0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
360f0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
36100 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
36110 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
36120 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
36130 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
36140 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
36150 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
36160 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
36170 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
36180 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
36190 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
361a0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
361b0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
361c0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
361d0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
361e0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
361f0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
36200 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
36210 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
36220 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
36230 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
36240 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
36250 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  rs..*/.typedef v
36260 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
36270 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
36280 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
36290 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
362a0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
362b0 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
362c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
362d0 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
362e0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
362f0 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
36300 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
36310 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
36320 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
36330 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36340 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
36350 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36360 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
36370 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
36380 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
36390 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
363a0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
363b0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
363c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
363d0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
363e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
363f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
36400 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
36410 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
36420 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
36430 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
36440 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
36450 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
36460 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
36470 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
36480 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
36490 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
364a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
364b0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
364c0 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
364d0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
364e0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
364f0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
36500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36510 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
36520 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
36530 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
36540 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
36550 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36560 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
36570 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
36580 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
36590 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
365a0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
365b0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
365c0 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
365d0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
365e0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
365f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36600 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61 6e  zeroblob(C,N) an
36610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36620 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e 29  _zeroblob64(C,N)
36630 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 73  .** interfaces s
36640 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
36650 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36660 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36670 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c 4f  n to be.** a BLO
36680 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
36690 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64 20   zero bytes and 
366a0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2e  N bytes in size.
366b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
366c0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
366d0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
366e0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
366f0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
36700 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36710 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
36720 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
36730 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
36740 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
36750 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
36760 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36770 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
36780 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36790 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
367a0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
367b0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
367c0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
367d0 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
367e0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
367f0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
36800 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
36810 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
36820 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36830 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
36840 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
36850 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
36860 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
36870 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
36880 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
36890 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
368a0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
368b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
368c0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
368d0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
368e0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
368f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36900 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
36910 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
36920 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
36930 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
36940 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
36950 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
36960 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
36970 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
36980 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
36990 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
369a0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
369b0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
369c0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
369d0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
369e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
369f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
36a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36a10 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
36a20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36a30 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
36a40 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
36a50 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
36a60 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
36a70 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
36a80 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
36a90 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
36aa0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
36ab0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36ac0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
36ad0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36ae0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
36af0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
36b00 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
36b10 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
36b20 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
36b30 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
36b40 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
36b50 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
36b60 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
36b70 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
36b80 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
36b90 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
36ba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36bb0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
36bc0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
36bd0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
36be0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
36bf0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
36c00 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
36c10 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
36c20 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
36c30 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
36c40 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
36c50 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
36c60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36c70 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
36c80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36c90 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
36ca0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
36cb0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
36cc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36cd0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
36ce0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
36cf0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
36d00 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
36d10 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
36d20 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
36d30 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
36d40 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
36d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36d60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
36d70 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
36d80 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
36d90 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
36da0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
36db0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
36dc0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
36dd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36de0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
36df0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36e00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36e10 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
36e20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36e30 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
36e40 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
36e50 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36e60 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36e70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
36e80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36e90 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
36ea0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36eb0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
36ec0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36ed0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36ee0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
36ef0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
36f00 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
36f10 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
36f20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36f30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
36f40 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
36f50 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36f60 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36f70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36f80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36f90 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
36fa0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36fb0 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
36fc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
36fd0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
36fe0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
36ff0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
37000 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
37010 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
37020 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37030 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
37040 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37050 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
37060 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
37070 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
37080 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
37090 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
370a0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
370b0 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
370c0 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
370d0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
370e0 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  y..** ^The sqlit
370f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
37100 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37110 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
37120 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c  ue of an.** appl
37130 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37140 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
37150 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20   text string in 
37160 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73  an encoding.** s
37170 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
37180 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29  fifth (and last)
37190 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
371a0 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a  h must be one.**
371b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
371c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
371d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
371e0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
371f0 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51  UTF16LE]..** ^SQ
37200 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
37210 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
37220 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
37230 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
37240 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
37250 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37260 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37270 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
37280 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37290 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
372a0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
372b0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
372c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
372d0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
372e0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
372f0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
37300 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
37310 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
37320 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
37330 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
37340 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37350 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
37360 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
37370 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
37380 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
37390 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
373a0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
373b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
373c0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
373d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
373e0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
373f0 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
37400 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
37410 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
37420 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
37430 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
37440 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
37450 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
37460 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
37470 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
37480 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
37490 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
374a0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
374b0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
374c0 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
374d0 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
374e0 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
374f0 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
37500 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
37510 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
37520 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
37530 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
37540 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
37550 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
37560 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
37570 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
37580 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
37590 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
375a0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
375b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
375c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
375d0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
375e0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
375f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
37600 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
37610 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
37620 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
37630 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
37640 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
37650 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
37660 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
37670 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
37680 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
37690 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
376a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
376b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
376c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
376d0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
376e0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
376f0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
37700 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
37710 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
37720 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
37730 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
37740 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
37750 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
37760 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
37770 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
37780 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
37790 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
377a0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
377b0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
377c0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
377d0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
377e0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
377f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
37800 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37810 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
37820 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
37830 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
37840 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
37850 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
37860 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
37870 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
37880 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
37890 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
378a0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
378b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
378c0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
378d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
378e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
378f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
37900 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
37910 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
37920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37930 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
37940 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  y of the.** [unp
37950 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
37960 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
37970 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
37980 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
37990 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
379a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
379b0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
379c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
379d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
379e0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
379f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
37a00 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
37a10 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
37a20 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
37a30 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
37a40 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
37a50 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
37a60 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
37a70 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
37a80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
37a90 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
37aa0 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
37ab0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
37ac0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37ad0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
37ae0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
37af0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
37b00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
37b10 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
37b20 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
37b30 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
37b40 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
37b50 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
37b60 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
37b70 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
37b80 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
37b90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37ba0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
37bb0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
37bc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
37bd0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
37be0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
37bf0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
37c00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
37c10 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
37c20 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37c30 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
37c40 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
37c50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
37c60 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  b64(sqlite3_cont
37c70 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ext*,const void*
37c80 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
37c90 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
37ca0 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64  ite3_uint64,void
37cb0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
37cc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37cd0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
37ce0 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
37cf0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37d00 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
37d10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
37d20 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
37d30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37d40 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
37d50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37d60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
37d70 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37d80 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
37d90 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
37da0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
37db0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37dc0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
37dd0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
37de0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37df0 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
37e00 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
37e10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37e20 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
37e30 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
37e40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37e50 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
37e60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
37e70 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
37e80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37e90 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
37ea0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
37eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37ec0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
37ed0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
37ee0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
37ef0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
37f00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36  te3_result_text6
37f10 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
37f20 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
37f30 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
37f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37f50 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
37f60 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
37f70 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
37f80 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  g);.void sqlite3
37f90 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
37fa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37fb0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
37fc0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
37fd0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
37fe0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
37ff0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38000 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
38010 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
38020 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
38030 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
38040 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
38050 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
38060 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
38070 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
38080 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
38090 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
380a0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
380b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
380c0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
380d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
380e0 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71  , int n);.int sq
380f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
38100 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
38110 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
38120 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a 0a 0a 2f  3_uint64 n);.../
38130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
38140 65 74 74 69 6e 67 20 54 68 65 20 53 75 62 74 79  etting The Subty
38150 70 65 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  pe Of An SQL Fun
38160 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ction.** METHOD:
38170 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
38180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
38190 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70  e3_result_subtyp
381a0 65 28 43 2c 54 29 20 66 75 6e 63 74 69 6f 6e 20  e(C,T) function 
381b0 63 61 75 73 65 73 20 74 68 65 20 73 75 62 74 79  causes the subty
381c0 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20 72 65 73  pe of.** the res
381d0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 5b 61 70  ult from the [ap
381e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
381f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20  d SQL function] 
38200 77 69 74 68 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  with .** [sqlite
38210 33 5f 63 6f 6e 74 65 78 74 5d 20 43 20 74 6f 20  3_context] C to 
38220 62 65 20 74 68 65 20 76 61 6c 75 65 20 54 2e 20  be the value T. 
38230 20 4f 6e 6c 79 20 74 68 65 20 6c 6f 77 65 72 20   Only the lower 
38240 38 20 62 69 74 73 20 0a 2a 2a 20 6f 66 20 74 68  8 bits .** of th
38250 65 20 73 75 62 74 79 70 65 20 54 20 61 72 65 20  e subtype T are 
38260 70 72 65 73 65 72 76 65 64 20 69 6e 20 63 75 72  preserved in cur
38270 72 65 6e 74 20 76 65 72 73 69 6f 6e 73 20 6f 66  rent versions of
38280 20 53 51 4c 69 74 65 3b 0a 2a 2a 20 68 69 67 68   SQLite;.** high
38290 65 72 20 6f 72 64 65 72 20 62 69 74 73 20 61 72  er order bits ar
382a0 65 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  e discarded..** 
382b0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 75  The number of su
382c0 62 74 79 70 65 20 62 79 74 65 73 20 70 72 65 73  btype bytes pres
382d0 65 72 76 65 64 20 62 79 20 53 51 4c 69 74 65 20  erved by SQLite 
382e0 6d 69 67 68 74 20 69 6e 63 72 65 61 73 65 0a 2a  might increase.*
382f0 2a 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  * in future rele
38300 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
38310 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
38320 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 73  result_subtype(s
38330 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
38340 75 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b 0a 0a  unsigned int);..
38350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38360 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
38370 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
38380 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
38390 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  3.**.** ^These f
383a0 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
383b0 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
383c0 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
383d0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
383e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
383f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
38400 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
38410 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
38420 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
38430 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
38440 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
38450 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
38460 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
38470 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
38480 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
38490 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
384a0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
384b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
384c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
384d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
384e0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
384f0 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
38500 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
38510 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
38520 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
38530 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
38540 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
38550 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
38560 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
38570 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
38580 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
38590 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
385a0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
385b0 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
385c0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
385d0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
385e0 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
385f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
38600 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
38610 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
38620 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
38630 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
38640 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
38650 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
38660 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
38670 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
38680 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
38690 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
386a0 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
386b0 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
386c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
386d0 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
386e0 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
386f0 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
38700 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
38710 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
38720 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
38730 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
38740 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
38750 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
38760 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
38770 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
38780 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
38790 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
387a0 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
387b0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
387c0 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
387d0 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
387e0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
387f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
38800 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
38