/ Hex Artifact Content
Login

Artifact fa62718f73553f06b2f2e362fd09ccb4e1cbb626:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20  _IOERR_VNODE    
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29  _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20  _IOERR_AUTH     
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29  _IOERR | (28<<8)
5610: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5620: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5630: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5640: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5660: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5670: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5680: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5690: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56a0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
56b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56c0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56f0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
5700: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5710: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
5730: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5740: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5750: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5760: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5770: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5780: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5790: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57b0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
57c0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57d0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57f0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5800: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5810: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5830: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5850: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5870: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5880: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5890: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
58a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58b0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
58d0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
5900: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
5910: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5930: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5940: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5950: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5980: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59c0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
59d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59e0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a00: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5a10: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5a20: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a50: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a90: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5aa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ab0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5ac0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ad0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5ae0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5af0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b10: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5b30: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b50: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b60: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ba0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5bb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bc0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5be0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c00: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c60: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c70: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c80: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5ca0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5cb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5cc0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ce0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5d00: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5d20: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5d30: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5dc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5de0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5e00: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5e10: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5e20: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e30: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e50: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e60: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e70: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e80: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5ea0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5eb0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5ec0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ed0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5ef0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5f00: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5f30: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f40: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f70: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f80: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5fc0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6000: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6010: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6020: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6030: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6090: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
60a0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
60d0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60e0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6150: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6160: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6190: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
61a0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
61d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61e0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6210: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6220: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6260: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6270: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6280: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6290: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
62b0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
62c0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
62d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6300: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6310: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6320: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6330: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6360: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6380: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6390: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63a0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
63b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
63c0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
63d0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
63e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
63f0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6400: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6410: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6420: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6430: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6440: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6450: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6460: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6470: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6480: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6490: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
64a0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
64b0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
64c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
64d0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
64e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
64f0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6500: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6510: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6520: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6530: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6540: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6550: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6560: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6570: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6580: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6590: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
65a0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
65b0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
65c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
65d0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
65e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
65f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6600: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6610: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6620: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6630: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6640: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6650: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6660: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6670: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6680: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6690: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
66b0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
66c0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
66d0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
66e0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
66f0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6700: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6710: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6720: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6730: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6740: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6750: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6760: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6770: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6780: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6790: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
67a0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
67b0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
67c0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
67d0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
67e0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
67f0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6800: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6810: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6820: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6830: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6840: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6850: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6860: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6870: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6880: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6890: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
68a0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
68b0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
68c0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
68d0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
68e0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
68f0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6900: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6910: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6920: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6930: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6950: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6970: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6980: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6990: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
69a0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6aa0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6ab0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6b10: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6b20: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b80: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6b90: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6bb0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6bc0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bf0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6c00: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6c20: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6c30: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6c50: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6c60: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6c70: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6c80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6c90: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6ca0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6cb0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6cc0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6cd0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6ce0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6cf0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d00: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6d20: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6d30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d40: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6d50: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6d60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6d70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6d80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6d90: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6da0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6db0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6dc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6dd0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6de0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6df0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6e00: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6e10: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6e20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6e30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e40: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6e50: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6e60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6e70: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6e80: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6e90: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ea0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6eb0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6ec0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6ed0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ee0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6ef0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6f00: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6f10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6f20: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6f30: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f40: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6f50: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6f60: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6f70: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6f80: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6f90: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6fa0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6fb0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6fc0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6fd0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6fe0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6ff0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7000: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7010: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7020: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7030: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7040: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7050: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7060: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7070: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7080: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7090: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
70a0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
70b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
70c0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
70d0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
70e0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
70f0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7100: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7110: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7120: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7130: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7140: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7150: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7160: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7170: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7180: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7190: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
71a0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
71b0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
71c0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
71d0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
71e0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
71f0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7200: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7210: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7220: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7230: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7240: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7250: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7260: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7270: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7280: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7290: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
72a0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
72b0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
72c0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
72d0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
72e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7380: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7390: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
73a0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
73b0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
73c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
73d0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
73e0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
73f0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7400: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7410: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7420: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7430: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7440: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7450: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7460: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7470: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7480: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7490: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
74a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
74b0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
74c0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
74d0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
74e0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
74f0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7500: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7510: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7520: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7530: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7540: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7560: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7570: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7580: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7590: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
75a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
75b0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
75c0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
75d0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
75e0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
75f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7600: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7610: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7620: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7630: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7640: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7650: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7660: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7670: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7680: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7690: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
76a0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
76b0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
76c0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
76d0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
76e0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
76f0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7700: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7710: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7720: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7740: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7760: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7770: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7780: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7790: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
77a0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
77b0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
77c0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
77d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77e0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
77f0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7800: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7810: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7820: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7830: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7840: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7850: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7870: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7880: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7890: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
78a0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
78b0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
78c0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
78d0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
78e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
78f0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7900: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7910: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7920: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7930: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7940: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7950: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7960: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7970: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7980: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7990: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
79a0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
79b0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
79c0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
79d0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
79e0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
79f0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7a00: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7a10: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7a20: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7a30: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7a50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a60: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7a70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a80: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7a90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7aa0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7ab0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ac0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7ad0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7ae0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7af0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7b00: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7b10: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7b20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7b30: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b40: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7b50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7b60: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7b70: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7b80: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7b90: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7ba0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7bb0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7bc0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7bd0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7be0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7bf0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7c00: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7c10: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7c20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7c30: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c40: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7c50: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7c60: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7c70: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7c80: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7c90: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7cb0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7cc0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7cd0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7ce0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7cf0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7d00: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7d10: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7d20: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7d30: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d40: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7d50: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7d60: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7d70: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7d80: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7d90: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7da0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7db0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7dc0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7dd0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7de0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7df0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7e00: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7e10: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7e20: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7e30: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e40: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7e50: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7e60: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7e70: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7e80: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7e90: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7ea0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7eb0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7ec0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7ed0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ee0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7ef0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f00: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f10: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f20: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7f30: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f40: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7f50: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7f60: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7f70: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7f80: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7f90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7fa0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7fb0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7fc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7fd0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7fe0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7ff0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8000: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8010: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8020: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8030: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8040: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8050: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8060: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8070: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8080: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8090: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
80a0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
80b0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
80c0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
80d0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
80e0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
80f0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8100: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8110: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8120: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8130: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8140: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8150: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8160: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8170: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8190: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
81c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81d0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
81e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81f0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8200: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8210: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8220: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8230: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8250: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8260: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8270: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8290: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
82a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
82b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
82d0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
82e0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
82f0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8300: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8310: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8320: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8330: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8340: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8350: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8360: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8370: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8380: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8390: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
83a0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
83b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
83c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
83d0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
83e0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
83f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8400: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8410: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8420: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8430: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8440: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8450: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8460: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8480: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8490: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
84a0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
84b0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
84c0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
84d0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
84e0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
84f0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8500: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8510: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8520: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8530: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8540: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8550: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8560: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8570: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8580: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8590: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
85a0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
85b0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
85c0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
85d0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
85e0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
85f0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8600: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8610: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8620: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8630: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8640: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8650: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8660: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8680: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8690: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86a0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
86b0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
86c0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
86d0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
86e0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
86f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8710: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8720: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8730: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8740: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8750: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8760: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8770: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8780: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8790: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
87a0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
87b0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
87c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
87d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
87e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87f0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8800: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8810: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8820: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8830: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8840: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8850: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8860: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8870: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8890: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
88a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
88c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
88d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88e0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
88f0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8910: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8920: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8930: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8940: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8950: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8960: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8970: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8980: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8990: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
89a0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
89b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89c0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
89d0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
89e0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
89f0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a00: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8a30: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a40: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8a50: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8a60: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8a70: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8a80: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8a90: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8aa0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ab0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8ac0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8ad0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8ae0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8af0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b00: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b10: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b20: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8b30: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b40: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8b50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8b60: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8b70: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8b80: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8b90: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8ba0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8bb0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8bc0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8bd0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8be0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8bf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8c00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8c20: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8c30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c40: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8c50: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8c60: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8c70: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8c80: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8c90: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8ca0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8cb0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8cc0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8cd0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ce0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8cf0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8d00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8d10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8d20: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8d30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d40: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8d50: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8d60: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8d70: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8d80: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8d90: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8da0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8db0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8dc0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8dd0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8de0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8df0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8e00: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8e10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8e20: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8e30: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e40: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8e50: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8e60: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8e70: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e80: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e90: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8ea0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8eb0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8ec0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8ed0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ee0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8ef0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8f00: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8f10: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8f20: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8f30: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f40: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8f50: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8f60: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8f70: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f80: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f90: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8fa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8fb0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8fc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8fd0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8ff0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9000: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9010: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9020: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9030: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9040: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9050: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9060: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9070: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9080: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9090: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
90a0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
90b0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
90c0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
90d0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
90e0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
90f0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9100: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9110: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9120: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9130: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9140: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9150: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9160: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9170: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9180: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9190: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
91a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
91b0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
91c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
91d0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
91e0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
91f0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9200: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9210: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9220: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9230: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9240: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9250: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9260: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9270: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9280: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9290: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
92a0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
92b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92c0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
92d0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
92e0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
92f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9300: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9310: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9320: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9330: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9340: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9350: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9360: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9370: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9380: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9390: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
93a0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
93b0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
93c0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
93d0: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
93e0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
93f0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9400: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9410: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9420: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9430: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9440: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9450: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9460: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9470: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9480: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9490: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
94a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
94b0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
94c0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
94d0: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
94e0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
94f0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9500: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9510: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9520: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9530: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9540: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9550: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9560: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9570: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9580: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9590: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
95a0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
95b0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
95c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
95d0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
95e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
95f0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9600: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9610: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9620: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9630: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9640: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9650: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9660: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9670: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9680: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9690: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
96a0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
96b0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
96c0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
96d0: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
96e0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
96f0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9700: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9710: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9720: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9730: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9740: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9750: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9760: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9770: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9780: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9790: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
97a0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
97b0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
97c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
97d0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
97e0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
97f0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9800: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9810: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9820: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9830: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9850: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9860: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9880: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9890: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
98a0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
98b0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
98c0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
98d0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
98e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
98f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9900: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9910: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9920: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9930: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9940: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9950: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9960: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9970: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9980: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9990: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
99a0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
99b0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
99c0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
99d0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
99e0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
99f0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9a00: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9a10: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9a20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9a30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9a40: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9a50: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9a60: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9a70: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a80: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a90: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9aa0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9ab0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9ac0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9ad0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9ae0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9af0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9b00: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9b10: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9b20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9b30: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9b40: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9b50: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9b60: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9b70: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b80: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b90: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9ba0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9bb0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9bc0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9bd0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9be0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9bf0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9c00: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9c10: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9c20: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9c30: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9c40: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9c50: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9c60: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9c70: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c80: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9ca0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9cb0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9cc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9cd0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9ce0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9cf0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9d00: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9d10: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9d20: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9d30: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9d40: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9d50: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9d60: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9d70: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d80: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d90: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9da0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9db0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9dc0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9dd0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9de0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9df0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9e00: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9e10: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9e20: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9e30: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9e40: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9e50: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9e60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9e70: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e80: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e90: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9ea0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9eb0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9ec0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9ed0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ee0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9ef0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9f00: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9f10: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9f20: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9f30: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9f40: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9f50: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9f60: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9f70: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f90: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9fa0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9fb0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9fc0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9fd0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9fe0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9ff0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a000: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a010: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a020: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a030: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a040: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a070: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a080: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a090: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a0a0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a0b0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a0c0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a0d0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a0e0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a0f0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a100: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a110: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a120: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a140: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a150: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a160: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a170: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a180: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a190: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a1a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a1b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a1c0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a1d0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a1e0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a1f0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a200: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a210: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a220: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a230: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a240: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a250: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a260: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a270: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a280: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a290: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a2a0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a2b0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a2d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a2e0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a2f0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a300: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a310: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a320: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a330: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a340: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a350: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a360: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a370: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a380: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a390: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a3a0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a3b0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a3c0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a3d0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a3e0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a3f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a400: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a410: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a420: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a430: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a440: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a450: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a460: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a470: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a480: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a490: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a4a0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a4b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a4c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a4d0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a4e0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a4f0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a500: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a510: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a520: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a530: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a540: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a550: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a560: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a570: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a580: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a590: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a5a0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a5b0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a5c0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a5d0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a5e0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a5f0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a600: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a610: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a620: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a630: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a640: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a650: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a660: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a670: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a680: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a690: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a6a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a6b0: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a6c0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a6d0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a6e0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a6f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a700: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a710: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a720: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a730: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a740: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a750: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a760: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a770: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a780: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a790: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a7a0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a7b0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a7c0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a7d0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a7e0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a7f0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a800: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a810: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a820: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a830: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a840: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a850: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a860: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a870: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a880: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a890: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a8a0: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a8b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a8c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a8d0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a8e0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a8f0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a900: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a910: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a920: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a930: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a940: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a950: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a960: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a970: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a980: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a990: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a9a0: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a9b0: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a9c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a9d0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a9e0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a9f0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
aa00: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
aa10: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
aa20: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
aa30: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
aa40: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
aa50: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
aa60: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
aa70: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
aa80: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
aa90: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
aaa0: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
aab0: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
aac0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
aad0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
aae0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
aaf0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
ab00: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
ab10: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
ab20: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
ab30: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
ab40: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
ab50: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
ab60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab70: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab80: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab90: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
aba0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
abb0: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
abc0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
abd0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
abe0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
abf0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
ac00: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
ac10: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
ac20: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
ac30: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
ac40: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
ac50: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
ac60: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac80: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac90: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
aca0: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
acb0: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
acc0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
acd0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
ace0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
acf0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ad00: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
ad10: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
ad20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
ad30: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
ad40: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
ad50: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ad60: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
ad70: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad80: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad90: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ada0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
adb0: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
adc0: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
add0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ade0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
adf0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ae00: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ae10: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ae20: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
ae30: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ae40: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
ae50: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ae60: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ae70: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae80: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae90: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
aea0: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
aeb0: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
aec0: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
aed0: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
aee0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
aef0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
af00: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
af10: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
af20: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
af30: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
af40: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
af50: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
af60: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
af70: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af80: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af90: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
afa0: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
afb0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
afc0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
afd0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
afe0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
aff0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
b000: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b010: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
b020: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
b030: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b040: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b050: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b060: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b070: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b080: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b090: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b0a0: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b0b0: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b0c0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b0d0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b0e0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b0f0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b100: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b110: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b120: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b130: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b140: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b150: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b160: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b170: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b180: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b190: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b1a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b1b0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b1c0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b1d0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b1e0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b1f0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b200: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b210: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b220: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b230: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b240: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b250: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b260: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b270: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b280: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b290: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b2a0: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b2b0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b2c0: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b2d0: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b2e0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b300: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b310: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b320: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b330: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b340: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b350: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b360: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b370: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b380: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b390: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b3a0: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b3b0: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b3c0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b3d0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b3e0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b3f0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b400: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b410: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b420: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b430: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b440: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b450: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b460: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b470: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b480: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b490: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b4a0: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b4b0: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b4c0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b4d0: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b4e0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b4f0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b500: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b510: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b520: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b530: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b540: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b550: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b560: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b570: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b580: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b590: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b5a0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b5b0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b5c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b5d0: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b5e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b5f0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b600: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b610: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b620: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b630: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b640: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b650: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b660: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b670: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b680: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b690: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b6a0: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b6b0: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b6c0: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b6d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b6e0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b6f0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b700: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b710: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b720: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b730: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
b740: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
b750: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
b760: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
b770: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
b780: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
b790: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
b7a0: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
b7b0: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
b7c0: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
b7d0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b7e0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
b7f0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
b800: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
b810: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
b820: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b830: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
b840: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
b850: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
b860: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
b870: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
b880: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
b890: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
b8a0: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
b8b0: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
b8c0: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
b8d0: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
b8e0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
b8f0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
b900: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
b910: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
b920: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
b930: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
b940: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
b950: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
b960: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
b970: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
b980: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
b990: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
b9a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b9b0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
b9c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b9d0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
b9e0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
b9f0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
ba00: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
ba10: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
ba20: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
ba30: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
ba40: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
ba50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
ba60: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
ba70: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
ba80: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
ba90: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
baa0: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
bab0: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
bac0: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
bad0: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
bae0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
baf0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
bb00: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
bb10: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
bb20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
bb30: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
bb40: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
bb50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
bb60: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
bb70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
bb80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
bb90: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bba0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
bbb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
bbc0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
bbd0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bbe0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
bbf0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
bc00: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bc10: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bc20: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bc30: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bc40: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
bc50: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bc60: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bc70: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bc80: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bc90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bca0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bcb0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bcc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bcd0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bce0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bcf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bd00: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bd10: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bd20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bd30: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
bd40: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
bd50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd60: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
bd70: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
bd80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd90: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
bda0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
bdb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bdc0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
bdd0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
bde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
bdf0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
be00: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
be10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
be20: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
be30: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
be40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
be50: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
be60: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
be80: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
be90: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
bea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
beb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bec0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
bed0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
bee0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
bef0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
bf00: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
bf10: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
bf20: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
bf30: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
bf40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
bf50: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bf60: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
bf70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
bf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf90: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
bfa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
bfb0: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
bfc0: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bfd0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
bfe0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c000: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
c010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
c020: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c030: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c040: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c050: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c060: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c070: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c080: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c090: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c0a0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c0b0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c0c0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c0d0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c0e0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c0f0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c100: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c110: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c120: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c130: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c140: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c150: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c160: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c170: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c180: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c190: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c1a0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c1b0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c1c0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c1d0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c1e0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c1f0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c200: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c210: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c220: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c230: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
c240: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
c250: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c260: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c270: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c280: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
c290: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
c2a0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
c2b0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
c2c0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
c2d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
c2e0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
c2f0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
c300: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
c310: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
c320: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
c330: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
c340: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
c350: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
c360: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
c370: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
c380: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
c390: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
c3a0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
c3b0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
c3c0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
c3d0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
c3e0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
c3f0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
c400: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
c410: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
c420: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
c430: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c440: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
c450: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
c460: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
c470: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
c480: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
c490: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c4a0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
c4b0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
c4c0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
c4d0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c4e0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
c4f0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
c500: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
c510: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
c520: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
c530: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
c540: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
c550: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
c560: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
c570: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
c580: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
c590: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
c5a0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
c5b0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
c5c0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
c5d0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
c5e0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
c5f0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
c600: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
c610: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
c620: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
c630: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c640: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
c650: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
c660: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
c670: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c680: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
c690: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
c6a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
c6b0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c6c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
c6d0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
c6e0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
c6f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c700: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
c710: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
c720: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
c730: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
c740: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
c750: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
c760: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
c770: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
c780: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c790: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c7a0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
c7b0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
c7c0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
c7d0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
c7e0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
c7f0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
c800: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
c810: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
c820: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
c830: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
c840: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
c850: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
c860: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
c870: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
c880: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
c890: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
c8a0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c8b0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
c8c0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
c8d0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
c8e0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
c8f0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
c900: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
c910: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
c920: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
c930: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
c940: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c950: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
c960: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
c970: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
c980: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
c990: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
c9a0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
c9b0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
c9c0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
c9d0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
c9e0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
c9f0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
ca00: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
ca10: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
ca20: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
ca30: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
ca40: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
ca50: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
ca60: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
ca70: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
ca80: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
ca90: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
caa0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
cab0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
cac0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
cad0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
cae0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
caf0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
cb00: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
cb10: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
cb20: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
cb30: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
cb40: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
cb50: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
cb60: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
cb70: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
cb80: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
cb90: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
cba0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
cbb0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
cbc0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cbd0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
cbe0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
cbf0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
cc00: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
cc10: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
cc20: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
cc30: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
cc40: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
cc50: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
cc60: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
cc70: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
cc80: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
cc90: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
cca0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
ccb0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
ccc0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
ccd0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
cce0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
ccf0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
cd00: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
cd10: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cd20: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
cd30: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
cd40: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
cd50: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
cd60: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
cd70: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cd80: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
cd90: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
cda0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
cdb0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
cdc0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
cdd0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
cde0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
cdf0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ce00: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
ce10: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ce20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
ce30: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ce40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
ce50: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ce60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ce70: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
ce80: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ce90: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
cea0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ceb0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
cec0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ced0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
cee0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
cef0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
cf00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
cf10: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
cf20: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
cf30: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
cf40: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
cf50: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
cf60: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
cf70: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
cf80: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
cf90: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
cfa0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
cfb0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
cfc0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
cfd0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
cfe0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
cff0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
d000: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
d010: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
d020: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
d030: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d050: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d060: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d070: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d080: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d090: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d0a0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d0b0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d0c0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d0d0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d0e0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d0f0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d100: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d110: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d120: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d130: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d140: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d150: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d170: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d180: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d190: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d1a0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d1b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d1c0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d1d0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d1e0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d1f0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d200: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d210: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d220: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d230: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
d240: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
d250: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
d260: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
d270: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
d280: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
d290: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d2a0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
d2b0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
d2c0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
d2d0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
d2e0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
d2f0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
d300: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
d310: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
d320: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
d330: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
d340: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
d350: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
d360: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
d370: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
d380: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
d390: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d3a0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
d3b0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
d3c0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
d3d0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
d3e0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
d3f0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
d400: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
d410: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
d420: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d430: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
d440: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
d450: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
d460: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
d470: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
d480: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
d490: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
d4a0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
d4b0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
d4c0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
d4d0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
d4e0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
d4f0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
d500: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
d510: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
d520: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
d530: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
d540: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
d550: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
d560: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d570: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
d580: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d590: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
d5a0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
d5b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d5c0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
d5d0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
d5e0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
d5f0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
d600: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
d610: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
d620: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
d630: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
d640: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
d650: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
d660: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
d670: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
d680: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
d690: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
d6a0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
d6b0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
d6c0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
d6d0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
d6e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d6f0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
d700: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
d710: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
d720: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d730: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
d740: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d750: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
d760: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
d770: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d780: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
d790: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d7a0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
d7b0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
d7c0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
d7d0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
d7e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
d7f0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
d800: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
d810: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
d820: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
d830: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
d840: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
d850: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
d860: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
d870: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
d880: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
d890: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
d8a0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d8b0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
d8c0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
d8d0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
d8e0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
d8f0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
d900: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
d910: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
d920: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
d930: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
d940: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
d950: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
d960: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
d970: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
d980: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
d990: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d9a0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
d9b0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
d9c0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
d9d0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
d9e0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
d9f0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
da00: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
da10: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
da20: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
da30: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
da40: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
da50: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
da60: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
da70: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
da80: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
da90: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
daa0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
dab0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
dac0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
dad0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
dae0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
daf0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
db00: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
db10: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
db20: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
db30: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
db40: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
db50: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
db60: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
db70: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
db80: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
db90: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
dba0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
dbb0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
dbc0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
dbd0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
dbe0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
dbf0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dc00: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
dc10: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
dc20: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
dc30: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
dc40: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
dc50: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
dc60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
dc70: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
dc80: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
dc90: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
dca0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dcb0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
dcc0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
dcd0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
dce0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
dcf0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
dd00: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
dd10: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
dd20: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
dd30: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
dd40: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
dd50: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
dd60: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
dd70: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
dd80: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
dd90: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
dda0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
ddb0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
ddc0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
ddd0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
dde0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
ddf0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
de00: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
de10: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
de20: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
de30: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
de40: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
de50: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
de60: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
de70: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
de80: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
de90: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
dea0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
deb0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
dec0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
ded0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
dee0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
def0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
df00: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
df10: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
df20: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
df30: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
df40: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
df50: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
df60: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
df70: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
df80: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
df90: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
dfa0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
dfb0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
dfc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
dfd0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
dfe0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
dff0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
e000: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
e010: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
e020: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
e030: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e040: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e050: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e060: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e070: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e080: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e090: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e0a0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e0b0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e0c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e0d0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e0e0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e0f0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e100: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e110: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e120: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e130: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e140: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e150: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e160: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e170: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e180: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e190: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e1a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e1b0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e1c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e1d0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e1e0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e1f0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e200: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e210: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e220: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e230: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
e240: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
e250: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e260: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
e270: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
e280: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
e290: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
e2a0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
e2b0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
e2c0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e2d0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e2e0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
e2f0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
e300: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
e310: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
e320: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
e330: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e340: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
e350: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
e360: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
e370: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e380: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
e390: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
e3a0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
e3b0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
e3c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e3d0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
e3e0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e3f0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
e400: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e410: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
e420: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
e430: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
e440: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e450: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
e460: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
e470: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
e480: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
e490: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
e4a0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
e4b0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
e4c0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
e4d0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
e4e0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
e4f0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
e500: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
e510: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
e520: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
e530: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
e540: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e550: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e560: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
e570: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
e580: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e590: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
e5a0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e5b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e5c0: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
e5d0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e5e0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
e5f0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
e600: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
e610: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
e620: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
e630: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e640: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
e650: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
e660: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
e670: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e680: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e690: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
e6a0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e6b0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
e6c0: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
e6d0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
e6e0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
e6f0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
e700: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e710: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e720: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
e730: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
e740: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
e750: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
e760: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e770: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e780: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
e790: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
e7a0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e7b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e7c0: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
e7d0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e7e0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e7f0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
e800: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e810: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
e820: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
e830: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
e840: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
e850: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
e860: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
e870: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
e880: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
e890: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e8a0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e8b0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
e8c0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
e8d0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
e8e0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
e8f0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
e900: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
e910: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e920: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
e930: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
e940: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
e950: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
e960: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
e970: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
e980: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
e990: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e9a0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
e9b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
e9c0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
e9d0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
e9e0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
e9f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ea00: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
ea10: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
ea20: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ea30: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
ea40: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
ea50: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
ea60: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
ea70: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ea80: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ea90: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
eaa0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
eab0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
eac0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ead0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
eae0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
eaf0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
eb00: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
eb10: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
eb20: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
eb30: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
eb40: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
eb50: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
eb60: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
eb70: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
eb80: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
eb90: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
eba0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
ebb0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
ebc0: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
ebd0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
ebe0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
ebf0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
ec00: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
ec10: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
ec20: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
ec30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ec40: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
ec50: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ec60: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
ec70: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
ec80: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ec90: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
eca0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ecb0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
ecc0: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
ecd0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ece0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
ecf0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ed00: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ed10: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
ed20: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
ed30: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
ed40: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
ed50: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ed60: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
ed70: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ed80: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
ed90: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
eda0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
edb0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
edc0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
edd0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ede0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
edf0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ee00: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
ee10: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
ee20: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
ee30: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
ee40: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ee50: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ee60: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
ee70: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ee80: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ee90: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
eea0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
eeb0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
eec0: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
eed0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
eee0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
eef0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
ef00: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
ef10: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
ef20: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ef30: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ef40: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
ef50: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ef60: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
ef70: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
ef80: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ef90: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
efa0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
efb0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
efc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
efd0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
efe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
eff0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
f000: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
f010: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
f020: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
f030: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f040: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f050: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f060: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f070: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f080: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f090: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f0a0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f0b0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f0c0: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f0d0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f0e0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f0f0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f100: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f110: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f120: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f130: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f140: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f150: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f160: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f170: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f180: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f190: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f1a0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f1b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f1c0: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f1d0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f1e0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f1f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f200: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f210: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f220: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f230: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
f240: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f250: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
f260: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
f270: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
f280: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
f290: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
f2a0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
f2b0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
f2c0: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
f2d0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
f2e0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
f2f0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
f300: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
f310: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f320: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f330: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f340: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f350: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
f360: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
f370: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f380: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f390: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
f3a0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
f3b0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
f3c0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
f3d0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
f3e0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
f3f0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
f400: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
f410: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
f420: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
f430: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
f440: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f450: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
f460: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
f470: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
f480: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f490: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
f4a0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f4b0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
f4c0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
f4d0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f4e0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
f4f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f500: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
f510: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f520: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
f530: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
f540: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f550: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
f560: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
f570: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
f580: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
f590: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f5a0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
f5b0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f5c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
f5d0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
f5e0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
f5f0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
f600: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
f610: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
f620: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
f630: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
f640: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
f650: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
f660: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
f670: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f680: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
f690: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
f6a0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
f6b0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
f6c0: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
f6d0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
f6e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f6f0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
f700: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
f710: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f720: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
f730: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f740: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
f750: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
f760: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
f770: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
f780: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
f790: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f7a0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
f7b0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f7c0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
f7d0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
f7e0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
f7f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
f800: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
f810: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
f820: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
f830: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
f840: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
f850: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
f860: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
f870: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
f880: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
f890: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
f8a0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f8b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f8c0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
f8d0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
f8e0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
f8f0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
f900: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
f910: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
f920: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
f930: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f940: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f950: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
f960: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
f970: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
f980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f990: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
f9a0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
f9b0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
f9c0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
f9d0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
f9e0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
f9f0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
fa00: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
fa10: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
fa20: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
fa30: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
fa40: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
fa50: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
fa60: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
fa70: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
fa80: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
fa90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
faa0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
fab0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
fac0: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
fad0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fae0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
faf0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
fb00: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
fb10: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
fb20: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
fb30: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
fb40: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
fb50: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
fb60: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
fb70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fb80: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
fb90: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
fba0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fbb0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
fbc0: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
fbd0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
fbe0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
fbf0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
fc00: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
fc10: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
fc20: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
fc30: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
fc40: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
fc50: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
fc60: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
fc70: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fc80: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
fc90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fca0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
fcb0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
fcc0: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
fcd0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fce0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
fcf0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
fd00: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fd10: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
fd20: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
fd30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
fd40: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
fd50: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
fd60: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
fd70: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
fd80: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
fd90: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
fda0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
fdb0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
fdc0: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
fdd0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
fde0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
fdf0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
fe00: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
fe10: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
fe20: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
fe30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
fe40: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
fe50: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
fe60: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
fe70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fe80: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
fe90: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
fea0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
feb0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
fec0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fed0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fee0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
fef0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
ff00: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
ff10: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
ff20: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
ff30: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
ff40: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
ff50: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ff60: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
ff70: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ff80: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
ff90: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ffa0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
ffb0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
ffc0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ffd0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
ffe0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
fff0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
10000 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
10010 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
10020 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
10030 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10040 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10050 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10060 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10070 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10080 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10090 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
100a0 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
100b0 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
100c0 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
100d0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
100e0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
100f0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
10100 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
10110 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
10120 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
10130 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10140 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10150 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10160 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10170 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10180 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10190 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
101a0 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
101b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
101c0 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
101d0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
101e0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
101f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
10200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10210 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
10220 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10230 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10240 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10250 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10260 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10270 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10280 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10290 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
102a0 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
102b0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
102c0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
102d0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
102e0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
102f0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
10300 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
10310 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10320 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10330 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10340 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10350 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10360 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10370 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10380 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10390 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33  * <b>The sqlite3
103a0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
103b0 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
103c0 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69  dsafe. The appli
103d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
103e0 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
103f0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
10400 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
10410 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
10420 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
10430 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10440 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a  running.</b>.**.
10450 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
10460 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
10470 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  e.** may only be
10480 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
10490 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
104a0 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
104b0 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
104c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
104d0 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
104e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
104f0 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
10500 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
10510 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
10520 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10530 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
10540 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10550 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
10560 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
10570 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
10580 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
10590 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
105a0 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
105b0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
105c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
105d0 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
105e0 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
105f0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
10600 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10610 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
10620 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10630 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
10640 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10650 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
10660 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
10670 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
10680 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
10690 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
106a0 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
106b0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
106c0 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
106d0 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
106e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
106f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
10700 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
10710 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
10720 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10730 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10740 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
10750 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
10760 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
10770 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
10780 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
10790 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
107a0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
107b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
107c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
107d0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
107e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
107f0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
10810 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
10820 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
10830 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10840 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10850 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
10860 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
10870 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
10880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
10890 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
108a0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
108b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
108c0 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
108d0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
108e0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
108f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10900 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
10910 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10920 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
10930 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10940 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
10950 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
10960 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
10970 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10980 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
10990 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
109a0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
109b0 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
109c0 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
109d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
109e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
109f0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10a00 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
10a10 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
10a20 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
10a30 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10a40 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
10a50 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
10a60 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
10a70 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
10a80 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
10a90 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
10aa0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10ab0 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10ac0 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10ad0 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10af0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10b00 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
10b10 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10b20 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
10b30 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
10b40 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
10b50 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
10b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10b70 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
10b80 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
10b90 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
10ba0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10bb0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10bc0 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10bd0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10be0 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10bf0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10c00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10c10 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
10c20 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10c30 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
10c40 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
10c50 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
10c60 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
10c70 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
10c80 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10c90 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
10ca0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10cb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10cc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10cd0 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10ce0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10cf0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10d00 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
10d10 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
10d20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10d30 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
10d40 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
10d50 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
10d60 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
10d70 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
10d80 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
10d90 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
10da0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10db0 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10dc0 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10dd0 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10de0 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10df0 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10e00 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
10e10 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
10e20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
10e30 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
10e40 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10e50 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
10e60 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
10e70 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
10e80 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
10e90 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
10ea0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10eb0 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10ec0 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10ed0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10ee0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10ef0 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10f00 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
10f10 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
10f20 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
10f30 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
10f40 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
10f50 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
10f60 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
10f70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
10f80 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
10f90 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
10fa0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10fb0 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10fc0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10fd0 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10fe0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10ff0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
11000 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
11010 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
11020 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
11030 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
11040 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
11050 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
11060 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
11070 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
11080 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
11090 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
110a0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
110b0 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
110c0 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
110d0 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
110e0 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
110f0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
11100 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
11110 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
11120 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
11130 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
11140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
11150 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
11160 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
11170 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11180 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
11190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
111a0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
111b0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
111c0 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
111d0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
111e0 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
111f0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
11200 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
11210 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
11220 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
11230 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
11240 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
11250 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
11260 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
11270 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11280 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
11290 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
112a0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
112b0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
112c0 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
112d0 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
112e0 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
112f0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
11300 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
11310 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
11320 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
11330 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
11340 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
11350 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
11360 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
11370 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
11380 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
11390 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
113a0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
113b0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
113c0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
113d0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
113e0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
113f0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
11400 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11410 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
11420 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
11430 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
11440 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
11450 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
11460 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
11470 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
11480 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
11490 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
114a0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
114b0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
114c0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
114d0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
114e0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
114f0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
11500 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
11510 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
11520 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
11530 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
11540 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
11550 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
11560 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
11570 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
11580 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
11590 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
115a0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
115b0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
115c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
115d0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
115e0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
115f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
11600 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11610 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11620 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
11630 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
11640 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
11650 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
11660 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
11670 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
11680 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
11690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
116a0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
116b0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
116c0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
116d0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
116e0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
116f0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11700 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11710 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11720 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11730 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11740 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
11750 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
11760 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
11770 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
11780 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
11790 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
117a0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
117b0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
117c0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
117d0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
117e0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
117f0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11810 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11820 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11830 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
11840 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
11850 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
11860 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
11870 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
11880 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
11890 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
118a0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
118b0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
118c0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
118d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
118e0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
118f0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
11900 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
11910 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
11920 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
11930 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
11940 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
11950 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
11960 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11970 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
11980 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
11990 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
119a0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
119b0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
119c0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
119d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
119e0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
119f0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
11a00 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
11a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11a20 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
11a30 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
11a40 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
11a50 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
11a60 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
11a70 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
11a80 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
11a90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
11aa0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11ab0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11ac0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11ad0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11ae0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11af0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11b00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11b10 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11b20 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11b30 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11b40 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
11b50 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
11b60 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
11b70 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
11b80 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
11b90 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
11ba0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11bb0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11bc0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11bd0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11be0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11bf0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11c00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11c10 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11c20 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11c30 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11c40 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
11c50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
11c60 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11c70 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
11c80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11c90 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
11ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11cb0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11cc0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11cd0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11ce0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11cf0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11d00 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11d10 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11d20 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11d30 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11d40 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
11d50 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
11d60 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11d70 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
11d80 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
11d90 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
11da0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11db0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11dc0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11dd0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11de0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11df0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11e00 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11e10 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11e20 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11e30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11e40 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
11e50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
11e60 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11e70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
11e80 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11e90 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
11ea0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11eb0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11ec0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11ed0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11ee0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11ef0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11f00 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11f10 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11f20 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11f30 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11f40 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11f50 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11f60 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11f70 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11f80 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11f90 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
11fa0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11fb0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11fc0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11fe0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11ff0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
12000 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
12010 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
12020 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
12030 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
12040 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12050 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12070 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
12080 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
12090 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
120a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
120b0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
120c0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
120d0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
120e0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
120f0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
12100 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
12110 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
12120 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
12130 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
12140 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12150 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12160 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12170 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12180 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12190 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
121a0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
121b0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
121c0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
121d0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
121e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
121f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12200 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12210 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12220 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
12230 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12240 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
12250 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12270 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12280 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
12290 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
122a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
122b0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
122c0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
122d0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
122e0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
122f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
12300 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
12310 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12320 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
12330 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
12340 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
12350 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
12360 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
12370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
12380 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12390 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
123a0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
123b0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
123c0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
123d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
123e0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
123f0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
12400 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12410 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
12420 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
12430 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
12440 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
12450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12460 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
12470 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
12480 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
12490 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
124a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
124b0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
124c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
124d0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
124e0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
124f0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
12500 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12510 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12520 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12530 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12540 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12550 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12560 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12570 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
12580 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
12590 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
125a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
125b0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
125c0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
125d0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
125e0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
125f0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12610 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12630 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
12640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12650 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12660 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12670 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69  NFIG_MALLOC opti
12680 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12690 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
126a0 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
126b0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
126c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
126d0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
126e0 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
126f0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
12700 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
12710 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
12720 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12730 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12740 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
12750 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12760 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12770 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12780 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12790 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
127a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
127b0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
127c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
127d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
127e0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
127f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12800 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12810 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12820 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12830 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
12840 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12850 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
12860 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
12870 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70  FIG_GETMALLOC op
12880 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12890 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
128a0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
128b0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
128c0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
128d0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
128e0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
128f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12900 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
12910 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
12920 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
12930 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
12940 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12950 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
12960 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12970 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
12980 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
12990 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
129a0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
129b0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
129c0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
129d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
129e0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
129f0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12a00 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
12a10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12a20 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12a30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12a40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
12a50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12a70 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74  MSTATUS option t
12a80 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
12a90 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
12aa0 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64  ,.** interpreted
12ab0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77   as a boolean, w
12ac0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
12ad0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
12ae0 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65  lection of.** me
12af0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12b00 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
12b10 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
12b20 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12b30 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c  are.** disabled,
12b40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
12b50 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
12b60 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
12b70 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
12b80 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
12b90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
12ba0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
12bb0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
12bc0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
12bd0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
12be0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
12bf0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
12c00 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28  qlite3_status64(
12c10 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
12c20 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
12c30 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12c40 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
12c50 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
12c60 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
12c70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
12c80 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
12c90 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
12ca0 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
12cb0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12cc0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
12cd0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
12ce0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12d00 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
12d10 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12d20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12d30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12d40 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20  _SCRATCH option 
12d50 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12d60 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12d70 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
12d80 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61  can use for scra
12d90 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54  tch memory.  ^(T
12da0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
12db0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53  rguments.** to S
12dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12dd0 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72  ATCH:  A pointer
12de0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
12df0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
12e00 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
12e10 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
12e20 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
12e30 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
12e40 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
12e50 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
12e60 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
12e70 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12e80 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12e90 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68  ons (N).)^.** Th
12ea0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12eb0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
12ec0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
12ed0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
12ee0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
12ef0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12f00 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
12f10 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65  ill not use more
12f20 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
12f30 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
12f40 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  read..** ^SQLite
12f50 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
12f60 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75  est a scratch bu
12f70 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
12f80 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
12f90 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
12fa0 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  age size..** ^If
12fb0 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
12fc0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
12fd0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12fe0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12ff0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13000 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13010 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
13020 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13030 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
13040 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
13050 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a  mory needed.<p>.
13060 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70  ** ^When the app
13070 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65  lication provide
13080 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20  s any amount of 
13090 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75  scratch memory u
130a0 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  sing.** SQLITE_C
130b0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53  ONFIG_SCRATCH, S
130c0 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e  QLite avoids unn
130d0 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a  ecessary large.*
130e0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
130f0 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f  c|heap allocatio
13100 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e  ns]..** This can
13110 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72   help [Robson pr
13120 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f  oof|prevent memo
13130 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
13140 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68  ilures] due to h
13150 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61  eap.** fragmenta
13160 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f  tion in low-memo
13170 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  ry embedded syst
13180 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ems..** </dd>.**
13190 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
131a0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
131b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
131c0 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
131d0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
131e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
131f0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
13200 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
13210 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
13220 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
13230 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
13240 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
13250 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
13260 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13270 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
13280 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13290 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
132a0 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
132b0 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
132c0 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
132d0 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
132e0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
132f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13300 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
13310 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13320 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13330 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
13340 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
13350 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
13360 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
13370 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
13380 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
13390 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
133a0 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
133b0 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
133c0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
133d0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
133e0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
133f0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
13400 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
13410 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
13420 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
13430 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
13440 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
13450 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
13460 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
13470 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
13480 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
13490 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
134a0 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
134b0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
134c0 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
134d0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
134e0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
134f0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13500 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13510 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13520 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13530 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
13540 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
13550 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
13560 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
13570 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
13580 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
13590 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
135a0 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
135b0 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
135c0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
135d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
135e0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
135f0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
13600 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
13610 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
13620 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
13630 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
13640 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
13650 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13660 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
13670 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
13680 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
13690 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
136a0 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
136b0 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
136c0 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
136d0 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
136e0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
136f0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13700 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
13710 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
13720 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
13730 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13740 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
13750 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
13760 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
13770 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
13780 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
13790 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
137a0 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
137b0 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
137c0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
137d0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
137e0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
137f0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
13800 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
13810 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
13820 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
13830 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13840 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
13850 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
13860 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
13870 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13880 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13890 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
138a0 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
138b0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
138c0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
138d0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
138e0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
138f0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
13900 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
13910 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
13920 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
13930 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
13940 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
13950 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
13960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13970 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53  RATCH] and.** [S
13980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
13990 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65  ECACHE]..** ^The
139a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
139b0 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  EAP option is on
139c0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
139d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
139e0 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65  ed.** with eithe
139f0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13a00 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51  _MEMSYS3] or [SQ
13a10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
13a20 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73  YS5] and returns
13a30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
13a40 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74  R] if invoked ot
13a50 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65  herwise..** ^The
13a60 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13a70 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
13a80 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a  _CONFIG_HEAP:.**
13a90 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
13aa0 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
13ab0 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
13ac0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
13ad0 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
13ae0 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
13af0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
13b00 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
13b10 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
13b20 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
13b30 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
13b40 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
13b50 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
13b60 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
13b70 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
13b80 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
13b90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
13ba0 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
13bb0 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
13bc0 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
13bd0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
13be0 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
13bf0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
13c00 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ULL then the alt
13c10 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
13c20 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
13c30 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
13c40 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
13c50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13c60 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
13c70 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
13c80 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
13c90 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
13ca0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
13cb0 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
13cc0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13cd0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
13ce0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
13cf0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
13d00 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
13d10 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
13d20 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
13d30 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
13d40 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
13d50 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
13d60 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
13d70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13d80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13d90 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13da0 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
13db0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13dc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13dd0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
13de0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13df0 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70   which is a.** p
13e00 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13e10 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13e20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13e30 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
13e40 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
13e50 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e  specifies altern
13e60 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
13e70 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
13e80 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20  o be used.** in 
13e90 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20  place the mutex 
13ea0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
13eb0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
13ec0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
13ed0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
13ee0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
13ef0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13f00 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
13f10 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
13f20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13f30 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
13f40 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13f50 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13f60 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13f70 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13f80 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13f90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13fa0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
13fb0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
13fc0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
13fd0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
13fe0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
13ff0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
14000 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14010 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14020 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
14030 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14040 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14050 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14070 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
14080 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14090 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
140a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
140b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
140c0 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  TMUTEX option ta
140d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
140e0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
140f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14100 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14110 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14120 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14130 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
14140 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14150 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
14160 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
14170 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
14180 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
14190 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
141a0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
141b0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
141c0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
141d0 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
141e0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
141f0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
14200 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
14210 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
14220 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
14230 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
14240 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
14250 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14260 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14270 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
14280 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
14290 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
142a0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
142b0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
142c0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
142d0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
142e0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
142f0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14300 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14310 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14320 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14330 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
14340 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
14350 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14360 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
14370 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14380 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
14390 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
143a0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
143b0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
143c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
143d0 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b  ASIDE option tak
143e0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
143f0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a   that determine.
14400 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73  ** the default s
14410 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  ize of lookaside
14420 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20   memory on each 
14430 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14440 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69  tion]..** The fi
14450 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
14460 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
14470 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
14480 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
14490 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
144a0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
144b0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
144c0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
144d0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53  nnection.)^  ^(S
144e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
144f0 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74  KASIDE.** sets t
14500 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  he <i>default</i
14510 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
14520 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
14530 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14540 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b  ].** option to [
14550 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14560 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
14570 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
14580 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
14590 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
145a0 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
145b0 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
145c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
145d0 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
145e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
145f0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
14600 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14610 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
14620 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14630 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14640 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
14650 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
14660 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
14670 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54  ods2] object.  T
14680 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
14690 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65  fies.** the inte
146a0 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f  rface to a custo
146b0 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
146c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a  lementation.)^.*
146d0 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  * ^SQLite makes 
146e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
146f0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14700 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c  thods2] object.<
14710 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14720 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14730 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14740 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14750 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
14760 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
14770 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14780 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
14790 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
147a0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
147b0 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
147c0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
147d0 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
147e0 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a  QLite copies of.
147f0 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70  ** the current p
14800 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14810 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
14820 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
14830 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14840 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
14850 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14860 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
14870 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
14880 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
14890 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
148a0 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
148b0 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
148c0 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
148d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
148e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
148f0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
14900 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
14910 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
14920 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
14930 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
14940 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
14950 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
14960 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
14970 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
14980 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
14990 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
149a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
149b0 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
149c0 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
149d0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
149e0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
149f0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
14a00 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
14a10 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
14a20 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
14a30 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
14a40 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
14a50 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
14a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14a70 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
14a80 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
14a90 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
14aa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
14ab0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
14ac0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
14ad0 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
14ae0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
14af0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14b00 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
14b10 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
14b20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
14b30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14b40 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
14b50 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
14b60 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
14b70 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
14b80 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
14b90 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
14ba0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
14bb0 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
14bc0 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
14bd0 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
14be0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
14bf0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
14c00 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
14c10 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
14c20 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
14c30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
14c40 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
14c50 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
14c60 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
14c70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
14c80 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
14c90 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
14ca0 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
14cb0 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
14cc0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
14cd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14ce0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
14cf0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
14d00 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
14d10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14d20 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
14d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14d40 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51  .** <dd>^(The SQ
14d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
14d60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14d70 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14d80 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49  f type int..** I
14d90 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
14da0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14db0 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
14dc0 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
14dd0 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20  ter is zero,.** 
14de0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14df0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  g is globally di
14e00 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
14e10 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
14e20 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65  obally.** enable
14e30 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73  d, all filenames
14e40 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
14e50 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
14e60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
14e70 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
14e80 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70  en16()] or.** sp
14e90 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20  ecified as part 
14ea0 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d  of [ATTACH] comm
14eb0 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72  ands are interpr
14ec0 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65  eted as URIs, re
14ed0 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77  gardless.** of w
14ee0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
14ef0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
14f00 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  RI] flag is set 
14f10 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
14f20 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
14f30 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69  is opened. ^If i
14f40 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
14f50 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
14f60 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
14f70 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
14f80 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
14f90 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
14fa0 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
14fb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14fc0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
14fd0 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  ^(By default, UR
14fe0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
14ff0 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
15000 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
15010 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
15020 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
15030 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
15040 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
15050 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e  ymbol defined.)^
15060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15070 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
15080 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74  INDEX_SCAN]] <dt
15090 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  >SQLITE_CONFIG_C
150a0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
150b0 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  AN.** <dd>^The S
150c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
150d0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
150e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
150f0 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a  single integer.*
15100 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  * argument which
15110 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
15120 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20  as a boolean in 
15130 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20  order to enable 
15140 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  or disable.** th
15150 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
15160 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
15170 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69  ll table scans i
15180 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69  n the query opti
15190 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64  mizer..** ^The d
151a0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
151b0 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
151c0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
151d0 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
151e0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
151f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
15200 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
15210 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
15220 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
15230 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
15240 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
15250 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
15260 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
15270 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
15280 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
15290 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
152a0 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
152b0 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
152c0 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
152d0 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
152e0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
152f0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
15300 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
15310 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
15320 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
15330 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
15340 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
15350 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
15360 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
15370 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
15380 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
15390 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
153a0 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
153b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
153c0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
153d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
153e0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
153f0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
15400 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
15410 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
15420 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
15430 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
15440 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
15450 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
15460 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15470 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
15480 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
15490 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
154a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
154b0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
154c0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
154d0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
154e0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
154f0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
15500 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
15510 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
15520 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
15530 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
15540 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
15550 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
15560 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
15570 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
15580 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
15590 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
155a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
155b0 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
155c0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
155d0 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
155e0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
155f0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
15600 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
15610 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
15620 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
15630 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
15640 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
15650 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
15660 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
15670 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
15680 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
15690 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
156a0 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
156b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
156c0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
156d0 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
156e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
156f0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
15700 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
15710 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
15720 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
15730 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15740 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
15750 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
15760 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
15770 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
15780 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
15790 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
157a0 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
157b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
157c0 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
157d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
157e0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
157f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15800 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
15810 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
15820 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
15830 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
15840 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
15850 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
15860 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
15870 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
15880 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
15890 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
158a0 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
158b0 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
158c0 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
158d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
158e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
158f0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
15900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15910 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
15920 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15930 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
15940 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
15950 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
15960 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
15970 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
15980 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
15990 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
159a0 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
159b0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
159c0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
159d0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
159e0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
159f0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
15a00 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
15a10 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
15a20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
15a30 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
15a40 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
15a50 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
15a60 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
15a70 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
15a80 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
15a90 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
15aa0 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
15ab0 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20  ap size.** will 
15ac0 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  be silently trun
15ad0 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61  cated if necessa
15ae0 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f  ry so that it do
15af0 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68  es not exceed th
15b00 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  e.** compile-tim
15b10 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73  e maximum mmap s
15b20 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a  ize set by the.*
15b30 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d  * [SQLITE_MAX_MM
15b40 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65  AP_SIZE] compile
15b50 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a  -time option.)^.
15b60 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72  ** ^If either ar
15b70 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f  gument to this o
15b80 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76  ption is negativ
15b90 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67  e, then that arg
15ba0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e  ument is.** chan
15bb0 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69  ged to its compi
15bc0 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e  le-time default.
15bd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15be0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15bf0 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PSIZE]].** <dt>S
15c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15c10 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c  32_HEAPSIZE.** <
15c20 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
15c30 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15c40 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f  SIZE option is o
15c50 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
15c60 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
15c70 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f  mpiled for Windo
15c80 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ws with the [SQL
15c90 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
15ca0 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15cb0 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64  macro.** defined
15cc0 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  . ^SQLITE_CONFIG
15cd0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
15ce0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
15cf0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15d00 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
15d10 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
15d20 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
15d30 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
15d40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15d50 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
15d60 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15d70 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15d80 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  DRSZ.** <dd>^The
15d90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15da0 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69  CACHE_HDRSZ opti
15db0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15dc0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
15dd0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
15de0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
15df0 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20  and writes into 
15e00 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65  that integer the
15e10 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61   number of extra
15e20 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61  .** bytes per pa
15e30 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  ge required for 
15e40 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51  each page in [SQ
15e50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
15e60 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61  CACHE]..** The a
15e70 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73  mount of extra s
15e80 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61  pace required ca
15e90 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69  n change dependi
15ea0 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ng on the compil
15eb0 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c  er,.** target pl
15ec0 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69  atform, and SQLi
15ed0 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  te version..**.*
15ee0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15ef0 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  G_PMASZ]].** <dt
15f00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
15f10 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  MASZ.** <dd>^The
15f20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15f30 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  MASZ option take
15f40 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
15f50 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
15f60 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74   an unsigned int
15f70 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68  eger and sets th
15f80 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  e "Minimum PMA S
15f90 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c  ize" for the mul
15fa0 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f  tithreaded.** so
15fb0 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74  rter to that int
15fc0 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75  eger.  The defau
15fd0 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53  lt minimum PMA S
15fe0 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68  ize is set by th
15ff0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52  e.** [SQLITE_SOR
16000 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69  TER_PMASZ] compi
16010 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20  le-time option. 
16020 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65   New threads are
16030 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20   launched.** to 
16040 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f  help with sort o
16050 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d  perations when m
16060 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72  ultithreaded sor
16070 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c  ting.** is enabl
16080 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50  ed (using the [P
16090 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63  RAGMA threads] c
160a0 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20  ommand) and the 
160b0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e  amount of conten
160c0 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65  t.** to be sorte
160d0 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61  d exceeds the pa
160e0 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68  ge size times th
160f0 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65  e minimum of the
16100 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68  .** [PRAGMA cach
16110 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20  e_size] setting 
16120 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a  and this value..
16130 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
16140 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16150 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
16160 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
16170 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16180 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
16190 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
161a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
161b0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
161c0 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
161d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
161e0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
161f0 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
16200 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
16210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16220 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
16230 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
16240 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
16250 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16260 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
16270 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
16280 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
16290 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
162a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
162b0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
162c0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
162d0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
162e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
162f0 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
16300 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
16310 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
16320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16330 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
16340 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
16350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16360 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
16370 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
16380 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16390 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
163a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
163b0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
163c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
163d0 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
163e0 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
163f0 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
16400 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
16410 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
16420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16430 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
16440 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
16450 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16460 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
16470 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
16480 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
164a0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
164b0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
164c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
164d0 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
164e0 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
164f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16500 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
16510 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
16520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16530 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16540 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
16550 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
16560 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
16570 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16580 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
16590 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
165a0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
165b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
165c0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
165d0 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
165e0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
165f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
16600 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
16610 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
16620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16630 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
16640 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
16650 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
16660 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
16670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16680 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16690 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
166a0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
166b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
166c0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
166d0 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
166e0 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
166f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16700 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
16710 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
16720 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
16730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16740 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
16750 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
16760 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
16770 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
16780 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
16790 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
167a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
167b0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
167c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
167d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
167e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
167f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
16800 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
16810 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16820 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
16830 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
16840 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
16850 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
16860 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16870 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
16880 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
16890 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
168a0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
168b0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
168c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
168d0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
168e0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
168f0 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
16900 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16910 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
16920 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
16930 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
16940 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
16950 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
16960 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
16970 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
16980 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
16990 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
169a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
169b0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
169c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
169d0 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
169e0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
169f0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
16a00 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
16a10 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
16a20 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
16a30 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
16a40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16a50 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
16a60 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
16a70 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
16a80 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
16a90 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
16aa0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
16ab0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
16ac0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
16ad0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
16ae0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
16af0 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
16b00 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16b10 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
16b20 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
16b30 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
16b40 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
16b50 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
16b60 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
16b70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16b80 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
16b90 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
16ba0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
16bb0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
16bc0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
16bd0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
16be0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
16bf0 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
16c00 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
16c10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
16c20 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
16c30 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
16c40 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
16c50 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
16c60 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
16c70 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
16c80 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
16c90 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
16ca0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
16cb0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
16cc0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
16cd0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16ce0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
16cf0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
16d00 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
16d10 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
16d20 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
16d30 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
16d40 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
16d50 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
16d60 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
16d70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16d80 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
16d90 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
16da0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
16db0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
16dc0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
16dd0 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
16de0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
16df0 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
16e00 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
16e10 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
16e20 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
16e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
16e40 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
16e50 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
16e60 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
16e70 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
16e80 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
16e90 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
16ea0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
16eb0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
16ec0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
16ed0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
16ee0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
16ef0 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
16f00 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16f10 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
16f20 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
16f30 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
16f40 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
16f50 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
16f60 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
16f70 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
16f80 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
16f90 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
16fa0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
16fb0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
16fc0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
16fd0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
16fe0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
16ff0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
17000 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17010 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
17020 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
17030 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
17040 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
17050 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
17060 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
17070 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
17080 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
17090 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
170a0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
170b0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
170c0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
170d0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
170e0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
170f0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17100 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
17110 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
17120 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
17130 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
17140 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
17150 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
17160 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
17170 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17180 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
17190 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
171a0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
171b0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
171c0 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
171d0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
171e0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
171f0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
17200 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
17210 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
17220 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
17230 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
17240 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
17250 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
17260 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
17270 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
17280 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
17290 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
172a0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
172b0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
172c0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
172d0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
172e0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
172f0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
17300 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
17310 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
17320 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
17330 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
17340 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17350 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
17360 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
17370 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
17380 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
17390 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
173a0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
173b0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
173c0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
173d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
173e0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
173f0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
17400 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
17410 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
17420 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
17430 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
17440 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17450 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
17460 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
17470 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
17480 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
17490 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
174a0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
174b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
174c0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
174d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
174e0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
174f0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
17500 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
17510 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
17520 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
17530 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
17540 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
17550 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
17560 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
17570 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
17580 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
17590 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
175a0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
175b0 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
175c0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
175d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
175e0 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
175f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
17600 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  3.**.** ^Each en
17610 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
17620 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
17630 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
17640 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
17650 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
17660 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
17670 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
17680 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
17690 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
176a0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
176b0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
176c0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
176d0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
176e0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
176f0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
17700 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
17710 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
17720 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
17730 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
17740 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
17750 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
17760 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
17770 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
17780 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
17790 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
177a0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
177b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
177c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
177d0 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (D) interface re
177e0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
177f0 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73  ] of the .** mos
17800 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
17810 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
17820 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
17830 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
17840 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
17850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
17860 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f  ** ^Inserts into
17870 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
17880 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
17890 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66  recorded..** ^If
178a0 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
178b0 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f  INSERT]s into ro
178c0 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61  wid tables.** ha
178d0 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
178e0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
178f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a   connection D, .
17900 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
17910 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17920 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72  d(D) returns zer
17930 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  o..**.** ^(If an
17940 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
17950 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
17960 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
17970 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
17980 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
17990 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
179a0 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
179b0 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
179c0 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
179d0 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
179e0 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
179f0 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
17a00 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
17a10 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17a20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
17a30 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
17a40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
17a50 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
17a60 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
17a70 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
17a80 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
17a90 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
17aa0 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
17ab0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
17ac0 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
17ad0 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
17ae0 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
17af0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
17b00 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
17b10 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
17b20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17b30 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
17b40 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
17b50 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
17b60 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
17b70 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
17b80 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
17b90 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
17ba0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
17bb0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
17bc0 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
17bd0 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
17be0 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
17bf0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
17c00 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
17c10 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
17c20 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
17c30 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
17c40 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
17c50 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
17c60 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
17c70 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
17c80 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
17c90 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
17ca0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
17cb0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
17cc0 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
17cd0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
17ce0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
17cf0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
17d00 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
17d10 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
17d20 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
17d30 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
17d40 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
17d50 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
17d60 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
17d70 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
17d80 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
17d90 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
17da0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
17db0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
17dc0 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
17dd0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
17de0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
17df0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
17e00 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
17e10 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
17e20 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
17e30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
17e40 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
17e50 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
17e60 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
17e70 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
17e80 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
17e90 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
17ea0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
17eb0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
17ec0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
17ed0 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
17ee0 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
17ef0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
17f00 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
17f10 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
17f20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
17f30 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
17f40 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17f50 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
17f60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17f70 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
17f80 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
17f90 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
17fa0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
17fb0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17fc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17fd0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  rows modified, i
17fe0 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65  nserted or.** de
17ff0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
18000 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
18010 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
18020 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  ATE or DELETE.**
18030 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
18040 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18050 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
18060 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  by the only para
18070 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75  meter..** ^Execu
18080 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
18090 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
180a0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f  ment does not mo
180b0 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a  dify the value.*
180c0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  * returned by th
180d0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
180e0 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ** ^Only changes
180f0 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62   made directly b
18100 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
18110 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
18120 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20  tatement are.** 
18130 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78  considered - aux
18140 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
18150 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45  aused by [CREATE
18160 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
18170 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69  ers], .** [forei
18180 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
18190 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  or [REPLACE] con
181a0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
181b0 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  on are not count
181c0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67  ed..** .** Chang
181d0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
181e0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
181f0 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41  d by .** [INSTEA
18200 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49  D OF trigger | I
18210 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
18220 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  rs] are not coun
18230 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20  ted. ^The value 
18240 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
18250 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18260 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  ) immediately af
18270 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55  ter an INSERT, U
18280 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c  PDATE or .** DEL
18290 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75  ETE statement ru
182a0 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61  n on a view is a
182b0 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79  lways zero. Only
182c0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f   changes made to
182d0 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73   real .** tables
182e0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
182f0 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d  .** Things are m
18300 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
18310 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  if the sqlite3_c
18320 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
18330 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64  n is.** executed
18340 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72   while a trigger
18350 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e   program is runn
18360 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61  ing. This may ha
18370 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70  ppen if the.** p
18380 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20  rogram uses the 
18390 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
183a0 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20  unction], or if 
183b0 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62  some other callb
183c0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
183d0 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f  invokes sqlite3_
183e0 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74  changes() direct
183f0 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a  ly. Essentially:
18400 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
18410 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20    <li> ^(Before 
18420 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67  entering a trigg
18430 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76  er program the v
18440 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
18450 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74  .**        sqlit
18460 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
18470 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20  ction is saved. 
18480 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65  After the trigge
18490 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20  r program .**   
184a0 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65       has finishe
184b0 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  d, the original 
184c0 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65  value is restore
184d0 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c  d.)^.** .**   <l
184e0 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72  i> ^(Within a tr
184f0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61  igger program ea
18500 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ch INSERT, UPDAT
18510 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a  E and DELETE .**
18520 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
18530 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65  t sets the value
18540 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
18550 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
18560 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63  **        upon c
18570 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72  ompletion as nor
18580 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20  mal. Of course, 
18590 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20  this value will 
185a0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20  not include .** 
185b0 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67         any chang
185c0 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  es performed by 
185d0 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73  sub-triggers, as
185e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
185f0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
18600 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20    value will be 
18610 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72  saved and restor
18620 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75  ed after each su
18630 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75  b-trigger has ru
18640 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  n.)^.** </ul>.**
18650 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73   .** ^This means
18660 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61   that if the cha
18670 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
18680 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29  ion (or similar)
18690 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74   is used.** by t
186a0 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c  he first INSERT,
186b0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
186c0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
186d0 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74  in a trigger, it
186e0 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65   .** returns the
186f0 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68   value as set wh
18700 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73  en the calling s
18710 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65  tatement began e
18720 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66  xecuting..** ^If
18730 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74   it is used by t
18740 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62  he second or sub
18750 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61  sequent such sta
18760 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
18770 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67  trigger .** prog
18780 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72  ram, the value r
18790 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73  eturned reflects
187a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
187b0 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20  ows modified by 
187c0 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  the .** previous
187d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
187e0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
187f0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
18800 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  ame trigger..**.
18810 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
18820 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
18830 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
18840 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
18850 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
18860 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
18870 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
18880 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
18890 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
188a0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
188b0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
188c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
188d0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
188e0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
188f0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
18900 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
18910 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
18920 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
18930 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
18940 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
18950 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
18960 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
18970 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
18980 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
18990 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
189a0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
189b0 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
189c0 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  l number of rows
189d0 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66   inserted, modif
189e0 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ied or.** delete
189f0 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54  d by all [INSERT
18a00 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ], [UPDATE] or [
18a10 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
18a20 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20  ts completed.** 
18a30 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
18a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61  se connection wa
18a50 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64  s opened, includ
18a60 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74  ing those execut
18a70 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
18a80 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18a90 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  s. ^Executing an
18aa0 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
18ab0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
18ac0 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74   does not affect
18ad0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18ae0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
18af0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a  otal_changes()..
18b00 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  ** .** ^Changes 
18b10 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
18b20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
18b30 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64  ions] are includ
18b40 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75  ed in the.** cou
18b50 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61  nt, but those ma
18b60 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45  de as part of RE
18b70 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
18b80 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a   resolution are.
18b90 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73  ** not. ^Changes
18ba0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
18bb0 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
18bc0 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  by INSTEAD OF tr
18bd0 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e  iggers .** are n
18be0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
18bf0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
18c00 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
18c10 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
18c20 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
18c30 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
18c40 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
18c50 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
18c60 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
18c70 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
18c80 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
18c90 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
18ca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
18cb0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
18cc0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18cd0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
18ce0 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
18cf0 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
18d00 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
18d10 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
18d20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
18d30 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
18d40 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
18d50 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
18d60 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
18d70 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  uery.** METHOD: 
18d80 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
18d90 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
18da0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
18db0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18dc0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
18dd0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
18de0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
18df0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
18e00 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
18e10 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
18e20 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
18e30 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
18e40 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
18e50 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
18e60 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18e70 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
18e80 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18e90 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18ea0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
18eb0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18ec0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
18ed0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
18ee0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
18ef0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
18f00 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
18f10 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
18f20 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
18f30 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
18f40 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18f50 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
18f60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18f70 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
18f80 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18f90 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18fa0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
18fb0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
18fc0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18fd0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
18fe0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
18ff0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
19000 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
19010 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
19020 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
19030 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
19040 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
19050 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
19060 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
19070 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
19080 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
19090 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
190a0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
190b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
190c0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
190d0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
190e0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
190f0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
19100 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
19110 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
19120 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
19130 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
19140 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
19150 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
19160 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
19170 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
19180 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19190 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
191a0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
191b0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
191c0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
191d0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
191e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
191f0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
19200 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
19210 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
19220 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
19230 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
19240 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
19250 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
19260 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
19270 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
19280 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
19290 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
192a0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
192b0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
192c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
192d0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
192e0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
192f0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
19300 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
19310 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
19320 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
19330 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
19340 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
19350 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
19360 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
19370 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
19380 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
19390 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
193a0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
193b0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
193c0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
193d0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
193e0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
193f0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
19400 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
19410 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
19420 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
19430 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19440 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
19450 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
19460 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
19470 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
19480 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
19490 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
194a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
194b0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
194c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
194d0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
194e0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
194f0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
19500 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
19510 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
19520 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
19530 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
19540 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
19550 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
19560 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
19570 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
19580 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
19590 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
195a0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
195b0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
195c0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
195d0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
195e0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
195f0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
19600 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
19610 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
19620 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
19630 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
19640 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
19650 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
19660 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
19670 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
19680 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
19690 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
196a0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
196b0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
196c0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
196d0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
196e0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
196f0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
19700 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
19710 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
19720 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
19730 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
19740 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
19750 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
19760 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
19770 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
19780 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
19790 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
197a0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
197b0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
197c0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
197d0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
197e0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
197f0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
19800 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
19810 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
19820 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
19830 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
19840 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
19850 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
19860 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
19870 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
19880 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
19890 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
198a0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
198b0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
198c0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
198d0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
198e0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
198f0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
19900 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
19910 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
19920 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
19930 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
19940 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
19950 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
19960 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
19970 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
19980 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
19990 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
199a0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
199b0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
199c0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
199d0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
199e0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
199f0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
19a00 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
19a10 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
19a20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
19a30 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
19a40 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
19a50 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
19a60 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19a70 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
19a80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
19a90 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
19aa0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
19ab0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
19ac0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
19ad0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
19ae0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
19af0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
19b00 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
19b10 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19b20 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
19b30 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
19b40 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
19b50 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
19b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
19b70 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
19b80 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
19b90 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
19ba0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
19bb0 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
19bc0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
19bd0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
19be0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
19bf0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19c00 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
19c10 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
19c20 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
19c30 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
19c40 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
19c50 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
19c60 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
19c70 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
19c80 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
19c90 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
19ca0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
19cb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
19cc0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
19cd0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
19ce0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
19cf0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
19d00 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19d10 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
19d20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
19d30 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
19d40 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
19d50 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
19d60 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
19d70 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
19d80 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
19d90 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
19da0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
19db0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
19dc0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
19dd0 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
19de0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
19df0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
19e00 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
19e10 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
19e20 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
19e30 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
19e40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19e50 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
19e60 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
19e70 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
19e80 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
19e90 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
19ea0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
19eb0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
19ec0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
19ed0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
19ee0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
19ef0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
19f00 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
19f10 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19f20 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
19f30 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
19f40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
19f50 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
19f60 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
19f70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
19f80 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
19f90 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
19fa0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
19fb0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
19fc0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
19fd0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
19fe0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
19ff0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1a000 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a010 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1a020 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1a030 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1a040 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1a050 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1a060 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1a070 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1a080 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1a090 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1a0a0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1a0b0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1a0c0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1a0d0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1a0e0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1a0f0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1a100 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1a110 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1a120 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1a130 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1a140 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1a150 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1a160 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1a170 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1a180 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1a190 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1a1a0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1a1b0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1a1c0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1a1d0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1a1e0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1a1f0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1a200 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1a210 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1a220 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1a230 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1a240 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1a250 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1a260 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1a270 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1a280 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1a290 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1a2a0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1a2b0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1a2c0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1a2d0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1a2e0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1a2f0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1a300 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1a310 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1a320 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1a330 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1a340 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1a350 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1a360 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1a370 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1a380 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1a390 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1a3a0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1a3b0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1a3c0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1a3d0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1a3e0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1a3f0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1a400 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1a410 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1a420 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1a430 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1a440 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1a450 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1a460 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1a470 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1a480 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1a490 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1a4a0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1a4b0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1a4c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1a4d0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1a4e0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1a4f0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1a500 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1a510 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1a520 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1a530 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1a540 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1a550 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1a560 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1a570 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1a580 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1a590 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1a5a0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1a5b0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1a5c0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1a5d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a5e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1a5f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1a600 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1a610 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1a620 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1a630 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1a640 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1a650 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1a660 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1a670 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1a680 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1a690 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a6a0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1a6b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1a6c0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1a6d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1a6e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1a6f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1a700 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1a710 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1a720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a730 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1a740 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1a750 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1a760 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1a770 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1a780 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1a790 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1a7a0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1a7b0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1a7c0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1a7d0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1a7e0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1a7f0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1a800 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1a810 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1a820 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1a830 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1a840 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1a850 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1a860 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1a870 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1a880 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1a890 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1a8a0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1a8b0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1a8c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1a8d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1a8e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1a8f0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1a900 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1a910 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1a920 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1a930 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1a940 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1a950 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1a960 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1a970 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1a980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1a990 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1a9a0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1a9b0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1a9c0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1a9d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1a9e0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1a9f0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1aa00 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1aa10 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1aa20 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1aa30 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1aa40 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1aa50 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1aa60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1aa70 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
1aa80 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
1aa90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1aaa0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
1aab0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
1aac0 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f  Queries.** METHO
1aad0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1aae0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1aaf0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1ab00 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1ab10 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1ab20 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1ab30 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1ab40 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1ab50 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1ab60 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1ab70 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1ab80 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1ab90 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1aba0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1abb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1abc0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1abd0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1abe0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1abf0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1ac00 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1ac10 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1ac20 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1ac30 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1ac40 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1ac50 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1ac60 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1ac70 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1ac80 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1ac90 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1aca0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1acb0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1acc0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1acd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1ace0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1acf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1ad00 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1ad10 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1ad20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1ad30 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1ad40 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1ad50 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1ad60 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1ad70 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1ad80 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1ad90 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1ada0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1adb0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1adc0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1add0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1ade0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1adf0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1ae00 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1ae10 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1ae20 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1ae30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1ae40 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1ae50 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1ae60 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1ae70 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1ae80 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1ae90 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1aea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1aeb0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1aec0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1aed0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1aee0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1aef0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1af00 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1af10 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1af20 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1af30 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1af40 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1af50 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1af60 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1af70 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1af80 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1af90 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1afa0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1afb0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1afc0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1afd0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1afe0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1aff0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b000 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1b010 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1b020 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1b030 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1b040 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1b050 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1b060 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1b070 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1b080 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1b090 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b0a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1b0b0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1b0c0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1b0d0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1b0e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1b0f0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1b100 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1b110 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1b120 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1b130 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1b140 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1b150 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1b160 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1b170 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b180 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1b190 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1b1a0 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1b1b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1b1c0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1b1d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b1e0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1b1f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b200 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1b210 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b220 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1b230 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b240 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1b250 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1b260 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1b270 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1b280 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b290 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1b2a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b2b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1b2c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b2d0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1b2e0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1b2f0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1b300 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1b310 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1b320 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1b330 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1b340 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1b350 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1b360 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1b370 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1b380 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1b390 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1b3a0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1b3b0 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1b3c0 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1b3d0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1b3e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1b3f0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1b400 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1b410 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1b420 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1b430 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1b440 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1b450 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1b460 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1b470 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1b480 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1b490 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1b4a0 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1b4b0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1b4c0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1b4d0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1b4e0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1b4f0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1b500 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1b510 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1b520 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1b530 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1b540 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1b550 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1b560 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b570 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1b580 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1b590 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1b5a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1b5b0 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1b5c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1b5d0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1b5e0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1b5f0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1b600 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1b610 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1b620 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1b630 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1b640 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1b650 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1b660 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1b670 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1b680 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1b690 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1b6a0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1b6b0 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1b6c0 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1b6d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1b6e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1b6f0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1b700 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1b710 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b720 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1b730 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1b740 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1b750 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1b760 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1b770 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1b780 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1b790 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1b7a0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1b7b0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1b7c0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1b7d0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1b7e0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1b7f0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1b800 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1b810 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1b820 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1b830 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1b840 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1b850 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1b860 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1b870 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1b880 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1b890 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1b8a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1b8b0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1b8c0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1b8d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1b8e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1b8f0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1b900 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1b910 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1b920 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1b930 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1b940 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1b950 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1b960 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1b970 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69  mon K&R formatti
1b980 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70  ng options,.** p
1b990 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1b9a0 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1b9b0 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c   formats, detail
1b9c0 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74  ed below..** Not
1b9d0 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74  e that some of t
1b9e0 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20  he more obscure 
1b9f0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1ba00 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a  ns from recent.*
1ba10 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e  * C-library stan
1ba20 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65  dards are omitte
1ba30 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c  d from this impl
1ba40 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ementation..**.*
1ba50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1ba60 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1ba70 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1ba80 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1ba90 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1baa0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1bab0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1bac0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1bad0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1bae0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1baf0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1bb00 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1bb10 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1bb20 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1bb30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1bb40 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1bb50 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1bb60 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1bb70 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1bb80 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1bb90 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1bba0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1bbb0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1bbc0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1bbd0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1bbe0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1bbf0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1bc00 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1bc10 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1bc20 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1bc30 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1bc40 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1bc50 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1bc60 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1bc70 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1bc80 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1bc90 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1bca0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1bcb0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1bcc0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1bcd0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1bce0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1bcf0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1bd00 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1bd10 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1bd20 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1bd30 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1bd40 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1bd50 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1bd60 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1bd70 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1bd80 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1bd90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1bda0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1bdb0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1bdc0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1bdd0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1bde0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1bdf0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1be00 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1be10 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1be20 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1be30 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1be40 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1be50 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1be60 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1be70 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1be80 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1be90 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1bea0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1beb0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1bec0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1bed0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1bee0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1bef0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1bf00 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1bf10 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1bf20 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1bf30 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1bf40 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1bf50 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1bf60 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1bf70 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1bf80 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1bf90 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1bfa0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1bfb0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1bfc0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1bfd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1bfe0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1bff0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1c000 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1c010 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1c020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1c030 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1c040 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1c050 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1c060 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1c070 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1c080 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1c090 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1c0a0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1c0b0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1c0c0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1c0d0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1c0e0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1c0f0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77   "%q", "%Q", "%w
1c100 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  " and "%z" optio
1c110 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1c120 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1c130 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1c140 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1c150 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1c160 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1c170 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1c180 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1c190 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1c1a0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1c1b0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1c1c0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1c1d0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1c1e0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1c1f0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1c200 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1c210 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1c220 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1c230 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1c240 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1c250 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1c260 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1c270 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1c280 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1c290 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1c2a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c2b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1c2c0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1c2d0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1c2e0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c2f0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1c300 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1c310 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1c320 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1c330 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c340 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1c350 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1c360 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1c370 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1c380 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1c390 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1c3a0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1c3b0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1c3c0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1c3d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c3e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1c3f0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1c400 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1c410 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1c420 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1c430 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1c440 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1c450 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1c460 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c470 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1c480 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c490 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1c4a0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1c4b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c4c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1c4d0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1c4e0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1c4f0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1c500 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1c510 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1c520 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1c530 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1c540 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1c550 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1c560 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1c570 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1c580 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1c590 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1c5a0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1c5b0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1c5c0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1c5d0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1c5e0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1c5f0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1c600 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1c610 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1c620 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1c630 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1c640 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1c650 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1c660 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1c670 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1c680 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1c690 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1c6a0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1c6b0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1c6c0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1c6d0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1c6e0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1c6f0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1c700 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1c710 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1c720 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1c730 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1c740 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1c750 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c760 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1c770 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1c780 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c790 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1c7a0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1c7b0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1c7c0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1c7d0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1c7e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1c7f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c800 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1c810 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1c820 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1c830 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1c840 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1c850 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1c860 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1c870 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1c880 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74  (The "%w" format
1c890 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c  ting option is l
1c8a0 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20  ike "%q" except 
1c8b0 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
1c8c0 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e  to.** be contain
1c8d0 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65  ed within double
1c8e0 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20  -quotes instead 
1c8f0 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  of single quotes
1c900 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61  , and it.** esca
1c910 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71  pes the double-q
1c920 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69  uote character i
1c930 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69  nstead of the si
1c940 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68  ngle-quote.** ch
1c950 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20  aracter.)^  The 
1c960 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1c970 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64  option is intend
1c980 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e  ed for safely in
1c990 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65  serting.** table
1c9a0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   and column name
1c9b0 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75  s into a constru
1c9c0 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  cted SQL stateme
1c9d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  nt..**.** ^(The 
1c9e0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1c9f0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1ca00 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1ca10 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1ca20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1ca30 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1ca40 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1ca50 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1ca60 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1ca70 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1ca80 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1ca90 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1caa0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1cab0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1cac0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1cad0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1cae0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1caf0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1cb00 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1cb10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1cb20 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1cb30 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1cb40 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1cb50 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1cb60 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1cb70 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1cb80 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1cb90 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1cba0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1cbb0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1cbc0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1cbd0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1cbe0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1cbf0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1cc00 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1cc10 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1cc20 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1cc30 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1cc40 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1cc50 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1cc60 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1cc70 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1cc80 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1cc90 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1cca0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1ccb0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1ccc0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1ccd0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1cce0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1ccf0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1cd00 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1cd10 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1cd20 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1cd30 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1cd40 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1cd50 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1cd60 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1cd70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1cd80 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1cd90 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1cda0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1cdb0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1cdc0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1cdd0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1cde0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1cdf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ce00 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29  ite3_malloc64(N)
1ce10 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a   routine works j
1ce20 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69  ust like.** sqli
1ce30 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78  te3_malloc(N) ex
1ce40 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1ce50 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69  n unsigned 64-bi
1ce60 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  t integer instea
1ce70 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64  d.** of a signed
1ce80 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e   32-bit integer.
1ce90 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1cea0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1ceb0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1cec0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1ced0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1cee0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1cef0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1cf00 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1cf10 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1cf20 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1cf30 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1cf40 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1cf50 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1cf60 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1cf70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1cf80 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1cf90 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1cfa0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1cfb0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1cfc0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1cfd0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1cfe0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1cff0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1d000 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1d010 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1d020 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1d030 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1d040 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1d050 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1d060 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1d070 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1d080 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1d090 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1d0a0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1d0b0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1d0c0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1d0d0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1d0e0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1d0f0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1d100 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1d110 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1d120 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1d130 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1d140 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72  alloc(X,N) inter
1d150 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1d160 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1d170 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1d180 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20  tion X to be at 
1d190 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a  least N bytes..*
1d1a0 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61  * ^If the X para
1d1b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d1c0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a  _realloc(X,N).**
1d1d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1d1e0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1d1f0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1d200 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1d210 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1d220 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20  )..** ^If the N 
1d230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1d240 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1d250 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1d260 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1d270 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1d280 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1d290 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1d2a0 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a  ite3_free(X)..**
1d2b0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1d2c0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61  c(X,N) returns a
1d2d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1d2e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1d2f0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1d300 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1d310 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  r NULL if insuff
1d320 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1d330 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e   available..** ^
1d340 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1d350 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1d360 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1d370 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1d380 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1d390 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1d3a0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1d3b0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1d3c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1d3d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d3e0 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69  X,N) and the pri
1d3f0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1d400 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1d410 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d420 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,N) returns NULL
1d430 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69   and N is positi
1d440 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  ve, then the.** 
1d450 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1d460 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1d470 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d480 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29  3_realloc64(X,N)
1d490 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
1d4a0 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  s the same as.**
1d4b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d4c0 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61  (X,N) except tha
1d4d0 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20  t N is a 64-bit 
1d4e0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1d4f0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1d500 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
1d510 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nteger..**.** ^I
1d520 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20  f X is a memory 
1d530 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69  allocation previ
1d540 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
1d550 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1d560 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1d570 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c  _malloc64(), sql
1d580 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20  ite3_realloc(), 
1d590 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1d5a0 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20  oc64(), then.** 
1d5b0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1d5c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
1d5d0 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79  e of that memory
1d5e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62   allocation in b
1d5f0 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61  ytes..** ^The va
1d600 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1d610 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1d620 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
1d630 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72   than the number
1d640 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71  .** of bytes req
1d650 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61  uested when X wa
1d660 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49  s allocated.  ^I
1d670 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f X is a NULL po
1d680 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71  inter then.** sq
1d690 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1d6a0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66  eturns zero.  If
1d6b0 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d   X points to som
1d6c0 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e  ething that is n
1d6d0 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e  ot.** the beginn
1d6e0 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ing of memory al
1d6f0 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20  location, or if 
1d700 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66  it points to a f
1d710 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64  ormerly.** valid
1d720 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d730 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20  on that has now 
1d740 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e  been freed, then
1d750 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
1d760 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   of sqlite3_msiz
1d770 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65  e(X) is undefine
1d780 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68  d and possibly h
1d790 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  armful..**.** ^T
1d7a0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
1d7b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
1d7c0 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f  lloc(), sqlite3_
1d7d0 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  realloc(),.** sq
1d7e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1d7f0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
1d800 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20  alloc64().** is 
1d810 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1d820 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1d830 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1d840 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1d850 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1d860 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1d870 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1d880 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1d890 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1d8a0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1d8b0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1d8c0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1d8d0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1d8e0 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1d8f0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1d900 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1d910 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1d920 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1d930 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1d940 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1d950 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1d960 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1d970 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1d980 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1d990 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1d9a0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1d9b0 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
1d9c0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
1d9d0 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
1d9e0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1d9f0 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
1da00 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
1da10 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1da20 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
1da30 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
1da40 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
1da50 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1da60 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1da70 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1da80 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1da90 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1daa0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1dab0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1dac0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1dad0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1dae0 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1daf0 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1db00 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1db10 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1db20 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1db30 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1db40 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1db50 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1db60 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1db70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1db80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1db90 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1dba0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1dbb0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1dbc0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1dbd0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1dbe0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1dbf0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1dc00 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1dc10 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1dc20 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1dc30 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1dc40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1dc50 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1dc60 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1dc70 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1dc80 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1dc90 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1dca0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1dcb0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1dcc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1dcd0 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
1dce0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1dcf0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1dd00 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
1dd10 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a  _uint64);.void *
1dd20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1dd30 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
1dd40 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1dd50 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
1dd60 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1dd70 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1dd80 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75  oid*);.sqlite3_u
1dd90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73  int64 sqlite3_ms
1dda0 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
1ddb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1ddc0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1ddd0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1dde0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1ddf0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1de00 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1de10 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1de20 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1de30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1de40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1de50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1de60 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1de70 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1de80 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1de90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1dea0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1deb0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1dec0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1ded0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1dee0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1def0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1df00 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1df10 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1df20 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1df30 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1df40 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1df50 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1df60 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1df70 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1df80 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1df90 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1dfa0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1dfb0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1dfc0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1dfd0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1dfe0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1dff0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1e000 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1e010 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1e020 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1e030 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1e040 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1e050 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1e060 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1e070 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1e080 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1e090 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1e0a0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1e0b0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1e0c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1e0d0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1e0e0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1e0f0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1e100 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1e110 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1e120 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1e130 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1e140 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1e150 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1e160 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1e170 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1e180 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1e190 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1e1a0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e1b0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1e1c0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1e1d0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1e1e0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
1e1f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1e200 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1e210 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1e220 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e230 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1e240 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1e250 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1e260 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1e270 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1e280 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1e290 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1e2a0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1e2b0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1e2c0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1e2d0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1e2e0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1e2f0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1e300 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1e310 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1e320 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1e330 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1e340 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1e350 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1e360 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1e370 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1e380 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1e390 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1e3a0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1e3b0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1e3c0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1e3d0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1e3e0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1e3f0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1e400 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1e410 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1e420 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1e430 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65  uffer P..** ^The
1e440 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e   P parameter can
1e450 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
1e460 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
1e470 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
1e480 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
1e490 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
1e4a0 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
1e4b0 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
1e4c0 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55  than one or a NU
1e4d0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50  LL pointer for P
1e4e0 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20  , then the PRNG 
1e4f0 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69  is.** seeded usi
1e500 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
1e510 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  tained from the 
1e520 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
1e530 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66  od of.** the def
1e540 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1e550 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
1e560 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
1e570 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1e580 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
1e590 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a  1 or more and a.
1e5a0 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68  ** non-NULL P th
1e5b0 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  en the pseudo-ra
1e5c0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1e5d0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1e5e0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1e5f0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1e600 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1e610 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1e620 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
1e630 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1e640 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1e650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e660 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1e670 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1e680 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
1e690 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1e6a0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1e6b0 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1e6c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1e6d0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1e6e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e6f0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1e700 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1e710 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1e720 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e730 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e740 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1e750 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1e760 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1e770 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e780 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e7a0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1e7b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1e7c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1e7d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1e7e0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1e7f0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1e800 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1e810 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1e820 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1e830 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1e840 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1e850 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e860 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1e870 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1e880 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1e890 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1e8a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e8b0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1e8c0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1e8d0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1e8e0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1e8f0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1e900 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1e910 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1e920 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1e930 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1e940 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1e950 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1e960 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1e970 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1e980 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1e990 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1e9a0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1e9b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e9c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1e9d0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1e9e0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1e9f0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1ea00 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1ea10 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1ea20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ea30 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1ea40 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1ea50 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1ea60 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1ea70 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1ea80 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1ea90 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1eaa0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1eab0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1eac0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1ead0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1eae0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1eaf0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1eb00 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1eb10 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1eb20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1eb30 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1eb40 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1eb50 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1eb60 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1eb70 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1eb80 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1eb90 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1eba0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1ebb0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1ebc0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1ebd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ebe0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1ebf0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1ec00 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1ec10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ec20 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1ec30 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1ec40 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1ec50 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1ec60 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1ec70 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1ec80 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1ec90 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1eca0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1ecb0 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1ecc0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1ecd0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1ece0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1ecf0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1ed00 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1ed10 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1ed20 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1ed30 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1ed40 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1ed50 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1ed60 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1ed70 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1ed80 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1ed90 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1eda0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1edb0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1edc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1edd0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1ede0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1edf0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1ee00 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1ee10 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1ee20 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1ee30 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1ee40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1ee50 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1ee60 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1ee70 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1ee80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1ee90 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1eea0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1eeb0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1eec0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1eed0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1eee0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1eef0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1ef00 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1ef10 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1ef20 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1ef30 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1ef40 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1ef50 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1ef60 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1ef70 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1ef80 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1ef90 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1efa0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1efb0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1efc0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1efd0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1efe0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1eff0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1f000 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1f010 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1f020 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1f030 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1f040 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1f050 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1f060 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1f070 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1f080 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1f090 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1f0a0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1f0b0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1f0c0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1f0d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1f0e0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1f0f0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1f100 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1f110 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1f120 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1f130 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1f140 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1f150 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1f160 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1f170 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1f180 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1f190 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1f1a0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1f1b0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1f1c0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1f1d0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1f1e0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1f1f0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1f200 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1f210 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1f220 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1f230 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1f240 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1f250 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1f260 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1f270 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1f280 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1f290 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1f2a0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1f2b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f2c0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1f2d0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1f2e0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1f2f0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1f300 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1f310 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1f320 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1f330 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1f340 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1f350 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1f360 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1f370 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1f380 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1f390 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1f3a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1f3b0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1f3c0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1f3d0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1f3e0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1f3f0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1f400 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1f410 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1f420 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1f430 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1f440 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f450 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1f460 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1f470 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1f480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f490 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1f4a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f4b0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1f4c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1f4d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1f4e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f4f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1f500 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1f510 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1f520 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1f530 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1f540 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1f550 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1f560 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1f570 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1f580 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1f590 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1f5a0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1f5b0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1f5c0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1f5d0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1f5e0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1f5f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1f600 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1f610 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1f620 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f630 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1f640 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1f650 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f660 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1f670 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1f680 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1f690 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1f6a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1f6b0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1f6c0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1f6d0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1f6e0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1f6f0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1f700 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1f710 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1f720 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1f730 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1f740 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1f750 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1f760 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1f770 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1f780 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1f790 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1f7a0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1f7b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1f7c0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1f7d0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1f7e0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1f7f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1f800 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1f810 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1f820 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1f830 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1f840 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1f850 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1f860 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1f870 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f880 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1f890 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f8a0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1f8b0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1f8c0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1f8d0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1f8e0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1f8f0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1f900 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1f910 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1f920 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1f930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1f940 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1f950 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1f960 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1f970 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1f980 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1f990 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1f9a0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1f9b0 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
1f9c0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
1f9d0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
1f9e0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1f9f0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1fa00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1fa10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fa20 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1fa30 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1fa40 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1fa50 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1fa60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1fa70 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1fa80 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1fa90 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1faa0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1fab0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1fac0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1fad0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1fae0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1faf0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1fb00 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1fb10 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1fb20 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1fb30 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1fb40 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1fb50 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1fb60 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1fb70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1fb80 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1fb90 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1fba0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1fbb0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1fbc0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1fbd0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1fbe0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1fbf0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1fc00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1fc10 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1fc20 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1fc30 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1fc40 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1fc50 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1fc60 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1fc70 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1fc80 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1fc90 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1fca0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1fcb0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1fcc0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1fcd0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1fce0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1fcf0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1fd00 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1fd10 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1fd20 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1fd30 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1fd40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1fd50 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1fd60 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1fd70 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1fd80 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1fd90 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1fda0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1fdb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fdc0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1fdd0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1fde0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1fdf0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1fe00 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1fe10 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1fe20 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1fe30 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1fe40 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1fe50 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1fe60 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1fe70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fe80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fe90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1fea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1feb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1fec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fed0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1fee0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1fef0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ff00 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ff10 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ff20 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1ff30 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1ff40 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ff50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ff60 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ff70 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1ff80 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1ff90 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ffa0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ffb0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ffc0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1ffd0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ffe0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fff0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20000 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
20010 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
20020 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
20030 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
20040 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20050 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
20060 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
20070 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
20080 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20090 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
200a0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
200b0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
200c0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
200d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
200e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
200f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
20100 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
20110 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
20120 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20130 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20140 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
20150 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
20160 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20170 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20190 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
201a0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
201b0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
201c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
201d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
201e0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
201f0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
20200 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20210 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20230 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
20240 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
20250 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
20260 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
20270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20280 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
20290 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
202a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
202b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
202c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
202d0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
202e0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
202f0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
20300 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20320 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
20330 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
20340 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
20350 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20370 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
20380 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
20390 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
203a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
203b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
203c0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
203d0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
203e0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
203f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20400 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
20410 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
20420 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
20430 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20440 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20450 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
20460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
20470 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
20480 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
20490 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
204a0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
204b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
204c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
204d0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
204e0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
204f0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
20500 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
20510 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
20520 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20530 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20540 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
20550 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
20560 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
20570 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20580 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20590 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
205a0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
205b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
205c0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
205d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
205e0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
205f0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
20600 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
20610 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20620 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20630 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
20640 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
20650 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
20660 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20680 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
20690 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
206a0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
206b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
206c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
206d0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
206e0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
206f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
20700 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20720 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
20730 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
20740 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20750 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20770 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
20780 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
20790 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
207a0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
207b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
207c0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
207d0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
207e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
207f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
20800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
20810 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
20820 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
20830 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
20840 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
20850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
20860 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
20870 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
20880 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
20890 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
208a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
208b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
208c0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
208d0 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
208e0 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
208f0 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
20900 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
20910 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20920 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
20930 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
20940 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
20950 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
20960 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
20970 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
20980 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
20990 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
209a0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
209b0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
209c0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
209d0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
209e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
209f0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
20a00 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
20a10 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
20a20 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
20a30 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
20a40 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
20a50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
20a60 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
20a70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
20a80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20a90 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
20aa0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
20ab0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
20ac0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
20ad0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20ae0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
20af0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
20b00 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
20b10 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
20b20 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
20b30 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
20b40 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
20b50 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
20b60 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
20b70 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
20b80 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
20b90 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
20ba0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
20bb0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
20bc0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
20bd0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
20be0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
20bf0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
20c00 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
20c10 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
20c20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
20c30 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
20c40 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
20c50 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
20c60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
20c70 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
20c80 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
20c90 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
20ca0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
20cb0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
20cc0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
20cd0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
20ce0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
20cf0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
20d00 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
20d10 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
20d20 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
20d30 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
20d40 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
20d50 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
20d60 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
20d70 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
20d80 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
20d90 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
20da0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
20db0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
20dc0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
20dd0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
20de0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
20df0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
20e00 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
20e10 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
20e20 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
20e30 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20e40 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
20e50 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
20e60 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
20e70 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
20e80 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
20e90 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
20ea0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
20eb0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
20ec0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
20ed0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
20ee0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20ef0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
20f00 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
20f10 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
20f20 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
20f30 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
20f40 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
20f50 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
20f60 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
20f70 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
20f80 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
20f90 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
20fa0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
20fb0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
20fc0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
20fd0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
20fe0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
20ff0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
21000 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
21010 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
21020 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
21030 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
21040 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
21050 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
21060 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
21070 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
21080 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
21090 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
210a0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
210b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
210c0 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
210d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
210e0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
210f0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
21100 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
21110 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
21120 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
21130 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
21140 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
21150 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
21160 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
21170 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
21180 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21190 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
211a0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
211b0 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
211c0 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
211d0 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
211e0 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
211f0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
21200 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
21210 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
21220 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
21230 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
21240 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
21250 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
21260 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
21270 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
21280 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
21290 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
212a0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
212b0 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
212c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
212d0 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
212e0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
212f0 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
21300 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
21310 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
21320 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
21330 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
21340 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
21350 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
21360 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
21370 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
21380 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
21390 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
213a0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
213b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
213c0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
213d0 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
213e0 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
213f0 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
21400 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
21410 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
21420 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
21430 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
21440 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
21450 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
21460 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
21470 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
21480 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
21490 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
214a0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
214b0 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
214c0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
214d0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
214e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
214f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
21500 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
21510 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
21520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
21530 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
21540 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
21550 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
21560 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
21570 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
21580 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
21590 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
215a0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
215b0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
215c0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
215d0 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f  Connection.** CO
215e0 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
215f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
21600 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
21610 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
21620 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
21630 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
21640 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
21650 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
21660 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
21670 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
21680 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
21690 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
216a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
216b0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
216c0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
216d0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
216e0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
216f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
21700 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
21710 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
21720 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
21730 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
21740 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
21750 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
21760 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
21770 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
21780 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
21790 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
217a0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
217b0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
217c0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
217d0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
217e0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
217f0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
21800 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
21810 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
21820 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
21830 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
21840 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
21850 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
21860 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
21870 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
21880 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
21890 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
218a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
218b0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
218c0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
218d0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
218e0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
218f0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
21900 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
21910 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
21920 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
21930 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
21940 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
21950 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
21960 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
21970 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
21980 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
21990 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
219a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
219b0 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
219c0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
219d0 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
219e0 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
219f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
21a00 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
21a10 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
21a20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
21a30 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
21a40 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
21a50 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
21a60 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
21a70 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
21a80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
21a90 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
21aa0 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
21ab0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
21ac0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
21ad0 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
21ae0 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
21af0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
21b00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21b10 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
21b20 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
21b30 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
21b40 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
21b50 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
21b60 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
21b70 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
21b80 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
21b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21ba0 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
21bb0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
21bc0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
21bd0 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
21be0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
21bf0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
21c00 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
21c10 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
21c20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21c30 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
21c40 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
21c50 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
21c60 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
21c70 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
21c80 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
21c90 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
21ca0 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
21cb0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
21cc0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21cd0 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
21ce0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
21cf0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
21d00 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
21d10 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
21d20 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
21d30 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
21d40 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21d50 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
21d60 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
21d70 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
21d80 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
21d90 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21da0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
21db0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
21dc0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
21dd0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
21de0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
21df0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
21e00 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
21e10 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
21e20 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
21e30 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
21e40 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
21e50 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
21e60 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
21e70 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21e80 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
21e90 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
21ea0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
21eb0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
21ec0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21ed0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
21ee0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
21ef0 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
21f00 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
21f10 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
21f20 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
21f30 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
21f40 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21f50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
21f60 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
21f70 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
21f80 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
21f90 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21fa0 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
21fb0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
21fc0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
21fd0 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
21fe0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
21ff0 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
22000 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
22010 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
22020 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
22030 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
22040 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
22050 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
22060 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
22070 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
22080 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22090 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
220a0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
220b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
220c0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
220d0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
220e0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
220f0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
22100 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
22110 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
22120 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
22130 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
22140 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
22150 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22160 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
22170 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
22180 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
22190 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
221a0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
221b0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
221c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
221d0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
221e0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
221f0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
22200 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
22210 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22220 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
22230 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
22240 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
22250 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
22260 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
22270 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
22280 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
22290 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
222a0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
222b0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
222c0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
222d0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
222e0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
222f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
22300 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
22310 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
22320 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
22330 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
22340 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
22350 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
22360 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
22370 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
22380 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
22390 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
223a0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
223b0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
223c0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
223d0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
223e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
223f0 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
22400 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
22410 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
22420 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
22430 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
22440 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
22450 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
22460 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
22470 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
22480 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
22490 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
224a0 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
224b0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
224c0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
224d0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
224e0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
224f0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
22500 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22510 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
22520 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
22530 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
22540 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
22550 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
22560 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
22570 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
22580 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
22590 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
225a0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
225b0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
225c0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
225d0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
225e0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
225f0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
22600 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
22610 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
22620 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
22630 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
22640 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
22650 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
22660 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
22670 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
22680 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
22690 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
226a0 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
226b0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
226c0 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
226d0 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
226e0 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
226f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22700 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
22710 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
22720 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
22730 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
22740 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
22750 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
22760 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
22770 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
22780 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
22790 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
227a0 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
227b0 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
227c0 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
227d0 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
227e0 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
227f0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
22800 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
22810 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
22820 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
22830 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
22840 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
22850 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
22860 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
22870 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
22880 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
22890 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
228a0 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
228b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
228c0 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
228d0 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
228e0 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
228f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
22900 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
22910 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
22920 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
22930 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
22940 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
22950 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
22960 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
22970 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
22980 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
22990 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
229a0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
229b0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
229c0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
229d0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
229e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
229f0 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
22a00 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
22a10 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
22a20 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
22a30 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
22a40 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
22a50 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
22a60 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
22a70 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
22a80 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
22a90 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
22aa0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
22ab0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
22ac0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
22ad0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
22ae0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
22af0 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
22b00 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
22b10 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
22b20 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
22b30 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
22b40 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
22b50 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
22b60 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
22b70 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
22b80 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
22b90 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
22ba0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
22bb0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
22bc0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
22bd0 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
22be0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
22bf0 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
22c00 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
22c10 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
22c20 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
22c30 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
22c40 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
22c50 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
22c60 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
22c70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
22c80 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
22c90 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
22ca0 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
22cb0 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
22cc0 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
22cd0 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
22ce0 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
22cf0 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
22d00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22d10 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
22d20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
22d30 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
22d40 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
22d50 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
22d60 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
22d70 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
22d80 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
22d90 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
22da0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
22db0 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
22dc0 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
22dd0 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
22de0 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
22df0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
22e00 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
22e10 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
22e20 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
22e30 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
22e40 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
22e50 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
22e60 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
22e70 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
22e80 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
22e90 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
22ea0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
22eb0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
22ec0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
22ed0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
22ee0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
22ef0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
22f00 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
22f10 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
22f20 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
22f30 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
22f40 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
22f50 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
22f60 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
22f70 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
22f80 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
22f90 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
22fa0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
22fb0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
22fc0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
22fd0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
22fe0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
22ff0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
23000 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
23010 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
23020 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
23030 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
23040 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
23050 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
23060 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
23070 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
23080 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
23090 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
230a0 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
230b0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
230c0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
230d0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
230e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
230f0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
23100 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
23110 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
23120 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
23130 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
23140 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
23150 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
23160 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
23170 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23180 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
23190 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
231a0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
231b0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
231c0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
231d0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
231e0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
231f0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
23200 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
23210 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
23220 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
23230 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
23240 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
23250 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
23260 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
23270 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
23280 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
23290 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
232a0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
232b0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
232c0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
232d0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
232e0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
232f0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
23300 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
23310 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
23320 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
23330 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
23340 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
23350 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
23360 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
23370 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
23380 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
23390 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
233a0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
233b0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
233c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
233d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
233e0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
233f0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
23400 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
23410 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
23420 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
23430 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
23440 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
23450 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
23460 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
23470 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
23480 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
23490 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
234a0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
234b0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
234c0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
234d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
234e0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
234f0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
23500 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
23510 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
23520 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
23530 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
23540 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
23550 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
23560 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
23570 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
23580 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
23590 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
235a0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
235b0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
235c0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
235d0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
235e0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
235f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
23600 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
23610 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
23620 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
23630 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
23640 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
23650 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
23660 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
23670 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
23680 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
23690 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
236a0 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
236b0 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
236c0 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
236d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
236e0 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
236f0 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
23700 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
23710 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
23720 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
23730 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
23740 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
23750 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
23760 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
23770 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
23780 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
23790 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
237a0 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
237b0 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
237c0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
237d0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
237e0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
237f0 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
23800 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
23810 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
23820 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
23830 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
23840 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
23850 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
23860 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
23870 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
23880 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
23890 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
238a0 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
238b0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
238c0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
238d0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
238e0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
238f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23900 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
23910 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
23920 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
23930 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
23940 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
23950 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
23960 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
23970 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
23980 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
23990 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
239a0 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
239b0 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
239c0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
239d0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
239e0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
239f0 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
23a00 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
23a10 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
23a20 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
23a30 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
23a40 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
23a50 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
23a60 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
23a70 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
23a80 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
23a90 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
23aa0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
23ab0 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
23ac0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
23ad0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
23ae0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
23af0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
23b00 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
23b10 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
23b20 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
23b30 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
23b40 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
23b50 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23b60 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
23b70 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
23b80 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
23b90 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
23ba0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
23bb0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
23bc0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
23bd0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
23be0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
23bf0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
23c00 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
23c10 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
23c20 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
23c30 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
23c40 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
23c50 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
23c60 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
23c70 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
23c80 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
23c90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23ca0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
23cb0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
23cc0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
23cd0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
23ce0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
23cf0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
23d00 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23d10 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
23d20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
23d30 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
23d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
23d50 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
23d60 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23d70 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
23d80 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
23d90 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
23da0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23db0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
23dc0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
23dd0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23de0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
23df0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
23e00 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
23e10 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
23e20 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
23e30 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
23e40 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
23e50 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
23e60 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
23e70 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
23e80 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
23e90 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
23ea0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
23eb0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
23ec0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
23ed0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
23ee0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
23ef0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
23f00 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
23f10 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
23f20 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
23f30 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
23f40 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
23f50 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
23f60 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
23f70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
23f80 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
23f90 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
23fa0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
23fb0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
23fc0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
23fd0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
23fe0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
23ff0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
24000 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
24010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
24020 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
24030 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
24040 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
24050 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
24060 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
24070 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
24080 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
24090 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
240a0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
240b0 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
240c0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
240d0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
240e0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
240f0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
24100 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
24110 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
24120 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
24130 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
24140 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
24150 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24160 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
24170 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
24180 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
24190 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
241a0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
241b0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
241c0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
241d0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
241e0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
241f0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
24200 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
24210 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
24220 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
24230 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
24240 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
24250 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
24260 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
24270 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
24280 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
24290 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
242a0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
242b0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
242c0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
242d0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
242e0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
242f0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
24300 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
24310 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
24320 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
24330 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
24340 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
24350 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
24360 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
24370 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
24380 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
24390 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
243a0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
243b0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
243c0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
243d0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
243e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
243f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
24400 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
24410 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
24420 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
24430 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
24440 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
24450 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
24460 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
24470 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
24480 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
24490 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
244a0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
244b0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
244c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
244d0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
244e0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
244f0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
24500 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
24510 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
24520 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24530 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
24540 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
24550 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
24560 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
24570 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
24580 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
24590 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
245a0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
245b0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
245c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
245d0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
245e0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
245f0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
24600 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
24610 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
24620 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
24630 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
24640 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
24650 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
24660 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
24670 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
24680 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
24690 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
246a0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
246b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
246c0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
246d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
246e0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
246f0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
24700 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
24710 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
24720 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
24730 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
24740 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
24750 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
24760 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
24770 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
24780 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
24790 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
247a0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
247b0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
247c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
247d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
247e0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
247f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
24800 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
24810 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
24820 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
24830 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
24840 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24850 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
24860 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
24870 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
24880 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
24890 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
248a0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
248b0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
248c0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
248d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
248e0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
248f0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
24900 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
24910 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
24920 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
24930 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
24940 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
24950 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
24960 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24970 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
24980 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
24990 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
249a0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
249b0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
249c0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
249d0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
249e0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
249f0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
24a00 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
24a10 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
24a20 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
24a30 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24a40 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
24a50 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
24a60 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
24a70 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
24a80 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
24a90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
24aa0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
24ab0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
24ac0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
24ad0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
24ae0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
24af0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
24b00 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
24b10 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
24b20 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
24b30 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
24b40 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
24b50 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
24b60 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
24b70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
24b80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24b90 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
24ba0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
24bb0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
24bc0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
24bd0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
24be0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
24bf0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
24c00 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
24c10 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24c20 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
24c30 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
24c40 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
24c50 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
24c60 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
24c70 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
24c80 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
24c90 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
24ca0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
24cb0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
24cc0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
24cd0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
24ce0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
24cf0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
24d00 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
24d10 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
24d20 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
24d30 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
24d40 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
24d50 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
24d60 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
24d70 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
24d80 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
24d90 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
24da0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
24db0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
24dc0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
24dd0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
24de0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
24df0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
24e00 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
24e10 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
24e20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
24e30 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
24e40 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
24e50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
24e60 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
24e70 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
24e80 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
24e90 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
24ea0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
24eb0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
24ec0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
24ed0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
24ee0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
24ef0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
24f00 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
24f10 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
24f20 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
24f30 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24f40 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
24f50 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
24f60 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
24f70 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
24f80 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
24f90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
24fa0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
24fb0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
24fc0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
24fd0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
24fe0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
24ff0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
25000 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
25010 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
25020 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
25030 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
25040 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
25050 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25060 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
25070 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
25080 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
25090 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
250a0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
250b0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
250c0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
250d0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
250e0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
250f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
25100 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
25110 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
25120 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
25130 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
25140 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
25150 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
25160 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
25170 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
25180 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
25190 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
251a0 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
251b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
251c0 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
251d0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
251e0 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
251f0 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
25200 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
25210 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
25220 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
25230 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
25240 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
25250 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
25260 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
25270 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
25280 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
25290 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
252a0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
252b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
252c0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
252d0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
252e0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
252f0 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
25300 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
25310 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
25320 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25330 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
25340 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25350 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
25360 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
25370 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
25380 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
25390 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
253a0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
253b0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
253c0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
253d0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
253e0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
253f0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
25400 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
25410 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
25420 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
25430 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
25440 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
25450 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
25460 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
25470 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
25480 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
25490 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
254a0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
254b0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
254c0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
254d0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
254e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
254f0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
25500 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
25510 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
25520 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25530 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
25540 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
25550 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
25560 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
25570 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
25580 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
25590 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
255a0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
255b0 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
255c0 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
255d0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
255e0 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
255f0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
25600 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
25610 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
25620 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
25630 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
25640 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
25650 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
25660 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
25670 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
25680 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
25690 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
256a0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
256b0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
256c0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
256d0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
256e0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
256f0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
25700 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
25710 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
25720 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
25730 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
25740 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
25750 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
25760 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
25770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
25780 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
25790 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
257a0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
257b0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
257c0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
257d0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
257e0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
257f0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
25800 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
25810 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
25820 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
25830 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
25840 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
25850 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
25860 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
25870 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
25880 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
25890 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
258a0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
258b0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
258c0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
258d0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
258e0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
258f0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
25900 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
25910 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
25920 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
25930 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
25940 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
25950 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
25960 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25970 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
25980 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
25990 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
259a0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
259b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
259c0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
259d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
259e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
259f0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
25a00 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
25a10 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
25a20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
25a30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
25a40 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
25a50 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
25a60 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
25a70 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73  ment that.** has
25a80 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69   been compiled i
25a90 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20  nto binary form 
25aa0 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20  and is ready to 
25ab0 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a  be evaluated..**
25ac0 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63  .** Think of eac
25ad0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
25ae0 61 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f  as a separate co
25af0 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20  mputer program. 
25b00 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   The.** original
25b10 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75   SQL text is sou
25b20 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65  rce code.  A pre
25b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
25b40 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68  object .** is th
25b50 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63  e compiled objec
25b60 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c  t code.  All SQL
25b70 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
25b80 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65  ed into a.** pre
25b90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
25ba0 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65  before it can be
25bb0 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
25bc0 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20  life-cycle of a 
25bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25be0 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c  nt object usuall
25bf0 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73  y goes like this
25c00 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
25c10 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
25c20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25c30 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  nt object using 
25c40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25c50 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  _v2()]..** <li> 
25c60 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
25c70 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
25c80 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
25c90 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
25ca0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
25cb0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
25cc0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
25cd0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
25ce0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
25cf0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
25d00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25d10 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
25d20 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
25d30 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
25d40 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
25d50 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
25d60 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
25d70 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
25d80 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
25d90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
25da0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64  * </ol>.*/.typed
25db0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
25dc0 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
25dd0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
25de0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
25df0 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  imits.** METHOD:
25e00 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
25e10 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
25e20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
25e30 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
25e40 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
25e50 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
25e60 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
25e70 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
25e80 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
25e90 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
25ea0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25eb0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
25ec0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
25ed0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
25ee0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
25ef0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
25f00 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
25f10 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
25f20 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
25f30 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
25f40 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
25f50 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
25f60 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
25f70 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
25f80 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
25f90 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
25fa0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
25fb0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
25fc0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
25fd0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
25fe0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
25ff0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
26000 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
26010 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
26020 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
26030 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
26040 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
26050 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
26060 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
26070 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
26080 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
26090 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
260a0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
260b0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
260c0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
260d0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
260e0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
260f0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
26100 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
26110 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
26120 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
26130 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
26140 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
26150 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
26160 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
26170 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
26180 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
26190 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
261a0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
261b0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
261c0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
261d0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
261e0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
261f0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
26200 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
26210 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
26220 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
26230 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
26240 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
26250 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
26260 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
26270 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
26280 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
26290 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
262a0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
262b0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
262c0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
262d0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
262e0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
262f0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
26300 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
26310 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
26320 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
26330 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
26340 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
26350 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
26360 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
26370 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
26380 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
26390 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
263a0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
263b0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
263c0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
263d0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
263e0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
263f0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
26400 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
26410 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
26420 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
26430 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
26440 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
26450 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
26460 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
26470 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
26480 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
26490 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
264a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
264b0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
264c0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
264d0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
264e0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
264f0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
26500 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
26510 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
26520 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
26530 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
26540 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
26550 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
26560 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
26570 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
26580 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
26590 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
265a0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
265b0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
265c0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
265d0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
265e0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
265f0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
26600 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
26610 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
26620 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
26630 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
26640 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
26650 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
26660 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
26670 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
26680 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
26690 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
266a0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
266b0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
266c0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
266d0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
266e0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
266f0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
26700 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
26710 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
26720 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
26730 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
26740 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26750 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
26760 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
26770 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
26780 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
26790 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
267a0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
267b0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
267c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
267d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
267e0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
267f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26800 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26810 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
26820 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
26830 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
26840 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
26850 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26860 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
26870 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
26880 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
26890 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
268a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
268b0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
268c0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
268d0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
268e0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
268f0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26900 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
26910 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
26920 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
26930 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
26940 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26950 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26960 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
26970 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26980 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
26990 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
269a0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
269b0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
269c0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
269d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
269e0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
269f0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
26a00 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26a10 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
26a20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26a30 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
26a40 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
26a50 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
26a60 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26a70 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
26a80 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
26a90 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
26aa0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
26ab0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26ac0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
26ad0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
26ae0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
26af0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
26b00 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
26b10 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
26b20 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
26b30 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
26b40 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
26b50 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
26b60 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
26b70 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
26b80 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26b90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26ba0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
26bb0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
26bc0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
26bd0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26be0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
26bf0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
26c00 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
26c10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26c20 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
26c30 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26c40 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
26c50 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26c60 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
26c70 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
26c80 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
26c90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26ca0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
26cb0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
26cc0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26cd0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
26ce0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26cf0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
26d00 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
26d10 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
26d20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
26d30 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
26d40 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
26d50 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
26d60 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
26d70 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
26d80 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
26d90 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
26da0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
26db0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
26dc0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
26dd0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
26de0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
26df0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
26e00 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
26e10 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
26e20 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
26e30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26e40 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
26e50 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
26e60 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
26e70 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26e80 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
26e90 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26ea0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26eb0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
26ec0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26ed0 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
26ee0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
26ef0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
26f00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26f10 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
26f20 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
26f30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
26f40 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
26f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26f60 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
26f70 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
26f80 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
26f90 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
26fa0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
26fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26fc0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
26fd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26fe0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
26ff0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
27000 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
27010 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
27020 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
27030 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
27040 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
27050 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
27060 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
27070 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
27080 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
27090 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
270a0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
270b0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
270c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
270d0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
270e0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
270f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27100 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27110 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
27120 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27130 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
27140 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
27150 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27160 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
27170 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
27180 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27190 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
271a0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
271b0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
271c0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
271d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
271e0 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
271f0 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
27200 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
27210 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
27220 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
27230 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
27240 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
27250 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
27260 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
27270 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
27280 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
27290 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
272a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
272b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
272c0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
272d0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
272e0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
272f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
27300 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
27310 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
27320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27330 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
27340 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
27350 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
27360 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
27370 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
27380 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
27390 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
273a0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
273b0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
273c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
273d0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
273e0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
273f0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
27400 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
27410 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
27420 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27430 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
27440 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
27450 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
27460 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
27470 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
27480 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
27490 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
274a0 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
274b0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
274c0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
274d0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
274e0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
274f0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
27500 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
27510 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
27520 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
27530 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
27540 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
27550 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
27560 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
27570 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
27580 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
27590 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
275a0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
275b0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
275c0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
275d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
275e0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
275f0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
27600 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
27610 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
27620 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
27630 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
27640 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
27650 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
27660 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
27670 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
27680 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
27690 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
276a0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
276b0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
276c0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
276d0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
276e0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
276f0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
27700 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
27710 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
27720 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
27730 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
27740 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27750 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
27760 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
27770 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27780 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
27790 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
277a0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
277b0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
277c0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
277d0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
277e0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
277f0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
27800 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
27810 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
27820 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
27830 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
27840 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
27850 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
27860 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
27870 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
27880 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
27890 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
278a0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
278b0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
278c0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
278d0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
278e0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
278f0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
27900 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
27910 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
27920 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
27930 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
27940 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
27950 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
27960 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
27970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27980 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
27990 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
279a0 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
279b0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
279c0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
279d0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
279e0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
279f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
27a00 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
27a10 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
27a20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
27a30 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
27a40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
27a50 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
27a60 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
27a70 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
27a80 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
27a90 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
27aa0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
27ab0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
27ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
27ad0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
27ae0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
27af0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
27b00 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
27b10 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
27b20 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
27b30 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
27b40 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
27b50 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
27b60 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
27b70 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
27b80 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
27b90 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
27ba0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
27bb0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
27bc0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
27bd0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
27be0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
27bf0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
27c00 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
27c10 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
27c20 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
27c30 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
27c40 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
27c50 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
27c60 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
27c70 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
27c80 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
27c90 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
27ca0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
27cb0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
27cc0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
27cd0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
27ce0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
27cf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27d00 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
27d10 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
27d20 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
27d30 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
27d40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
27d50 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
27d60 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
27d70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
27d80 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
27d90 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
27da0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
27db0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
27dc0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
27dd0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
27de0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
27df0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
27e00 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
27e10 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
27e20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
27e30 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
27e40 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
27e50 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
27e60 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
27e70 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
27e80 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
27e90 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
27ea0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
27eb0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
27ec0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
27ed0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
27ee0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
27ef0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
27f00 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
27f10 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
27f20 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
27f30 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
27f40 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
27f50 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
27f60 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
27f70 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
27f80 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
27f90 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
27fa0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
27fb0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
27fc0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
27fd0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
27fe0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
27ff0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
28000 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
28010 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
28020 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
28030 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
28040 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
28050 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
28060 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
28070 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
28080 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
28090 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
280a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
280b0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
280c0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
280d0 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
280e0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
280f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28100 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28110 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28120 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
28130 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28140 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
28150 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
28160 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
28170 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
28180 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
28190 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
281a0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
281b0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
281c0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
281d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
281e0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
281f0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
28200 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
28210 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
28220 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
28230 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
28240 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
28250 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
28260 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
28270 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
28280 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
28290 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
282a0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
282b0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
282c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
282d0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
282e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
282f0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28300 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28310 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28320 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28330 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28340 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28350 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
28360 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
28370 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
28380 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
28390 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
283a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
283b0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
283c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
283d0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
283e0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
283f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
28400 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
28410 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
28420 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
28430 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
28440 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
28450 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28460 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
28470 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
28480 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
28490 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
284a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
284b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
284c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
284d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
284e0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
284f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
28500 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28510 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
28520 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
28530 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
28540 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28550 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28560 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
28570 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28580 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28590 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
285a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
285b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
285c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
285d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
285e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
285f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
28600 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
28610 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44  nt SQL.** METHOD
28620 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
28630 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
28640 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
28650 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
28660 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
28670 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
28680 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
28690 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
286a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
286b0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
286c0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
286d0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
286e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
286f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
28700 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
28710 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
28720 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
28730 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
28740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28750 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
28760 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
28770 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
28780 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  se.** METHOD: sq
28790 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
287a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
287b0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
287c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
287d0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
287e0 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
287f0 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
28800 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
28810 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
28820 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
28830 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
28840 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
28850 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
28860 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28870 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
28880 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
28890 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
288a0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
288b0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
288c0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
288d0 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
288e0 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
288f0 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
28900 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
28910 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
28920 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
28930 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
28940 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
28950 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
28960 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
28970 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
28980 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
28990 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
289a0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
289b0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
289c0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
289d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
289e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
289f0 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
28a00 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
28a10 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
28a20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28a30 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
28a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
28a50 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
28a60 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
28a70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
28a80 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
28a90 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
28aa0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
28ab0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
28ac0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
28ad0 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
28ae0 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
28af0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
28b00 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
28b10 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
28b20 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
28b30 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
28b40 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
28b50 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
28b60 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
28b70 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
28b80 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
28b90 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
28ba0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
28bb0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
28bc0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
28bd0 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
28be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
28bf0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
28c00 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
28c10 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
28c20 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
28c30 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
28c40 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
28c50 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
28c60 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
28c70 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
28c80 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
28c90 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
28ca0 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  disk..*/.int sql
28cb0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
28cc0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
28cd0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
28ce0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
28cf0 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
28d00 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
28d10 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45  Been Reset.** ME
28d20 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
28d30 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
28d40 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28d50 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
28d60 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
28d70 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
28d80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28d90 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
28da0 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
28db0 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
28dc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
28dd0 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72   but has neither
28de0 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
28df0 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20  on (returned.** 
28e00 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72  [SQLITE_DONE] fr
28e10 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  om [sqlite3_step
28e20 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65  (S)]) nor.** bee
28e30 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
28e40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
28e50 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
28e60 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
28e70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28e80 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
28e90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
28ea0 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
28eb0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
28ec0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
28ed0 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
28ee0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28ef0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
28f00 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
28f10 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
28f20 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
28f30 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
28f40 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
28f50 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
28f60 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
28f70 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
28f80 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
28f90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28fa0 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
28fb0 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
28fc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
28fd0 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
28fe0 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
28ff0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
29000 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
29010 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
29020 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
29030 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
29040 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
29050 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
29060 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
29070 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
29080 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
29090 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
290a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
290b0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
290c0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
290d0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
290e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
290f0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
29100 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
29110 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
29120 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
29130 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
29140 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
29150 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
29160 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
29170 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
29180 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
29190 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
291a0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
291b0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
291c0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
291d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
291e0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
291f0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
29200 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
29210 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
29220 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
29230 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29240 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
29250 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
29260 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
29270 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
29280 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
29290 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
292a0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
292b0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
292c0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
292d0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
292e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
292f0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
29300 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
29310 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
29320 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
29330 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
29340 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
29350 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
29360 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29370 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
29380 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
29390 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
293a0 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72  e used to constr
293b0 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72  uct a new .** pr
293c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
293d0 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e  value from an un
293e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
293f0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
29400 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
29410 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
29420 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
29430 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
29440 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
29450 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
29460 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
29470 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
29480 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29490 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
294a0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
294b0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
294c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
294d0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
294e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
294f0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
29500 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
29510 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
29520 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
29530 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
29540 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
29550 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
29560 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
29570 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
29580 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
29590 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
295a0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
295b0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
295c0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
295d0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
295e0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
295f0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
29600 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
29610 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
29620 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
29630 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
29640 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
29650 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
29660 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
29670 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
29680 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
29690 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
296a0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
296b0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
296c0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
296d0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
296e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
296f0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
29700 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
29710 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29720 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
29730 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
29740 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
29750 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
29760 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
29770 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
29790 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
297a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
297b0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
297c0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
297d0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
297e0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
297f0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
29800 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
29810 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
29820 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
29830 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
29840 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
29850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
29860 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
29870 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
29880 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
29890 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
298a0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
298b0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
298c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
298d0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
298e0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
298f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
29900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29910 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
29920 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
29930 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
29940 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
29950 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
29960 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
29970 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
29980 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
29990 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
299a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
299b0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
299c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
299d0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
299e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
299f0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
29a00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29a10 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
29a20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29a30 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
29a40 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
29a50 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
29a60 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
29a70 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
29a80 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
29a90 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29aa0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
29ab0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
29ac0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
29ad0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
29ae0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
29af0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
29b00 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
29b10 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
29b20 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
29b30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
29b40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
29b50 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
29b60 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
29b70 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
29b80 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
29b90 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
29ba0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
29bb0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
29bc0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
29bd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
29be0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
29bf0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
29c00 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
29c10 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
29c20 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
29c30 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
29c40 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
29c50 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
29c60 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
29c70 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
29c80 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
29c90 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
29ca0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
29cb0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
29cc0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
29cd0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
29ce0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
29cf0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
29d00 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
29d10 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
29d20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
29d30 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
29d40 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
29d50 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
29d60 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
29d70 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
29d80 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
29d90 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
29da0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
29db0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
29dc0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
29dd0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
29de0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
29df0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
29e00 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
29e10 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
29e20 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
29e30 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
29e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
29e50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29e60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
29e70 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
29e80 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
29e90 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
29ea0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
29eb0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
29ec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29ed0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
29ee0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
29ef0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
29f00 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
29f10 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
29f20 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
29f30 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
29f40 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
29f50 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
29f60 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
29f70 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
29f80 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
29f90 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
29fa0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
29fb0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
29fc0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
29fd0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
29fe0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
29ff0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2a000 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2a010 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2a020 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2a030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a040 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2a050 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2a060 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2a070 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2a080 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2a090 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2a0a0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2a0b0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2a0c0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2a0d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2a0e0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2a0f0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2a100 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2a110 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2a120 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2a130 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2a140 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2a150 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2a160 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2a170 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a180 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2a190 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2a1a0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
2a1b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2a1c0 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
2a1d0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
2a1e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2a1f0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
2a200 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
2a210 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
2a220 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2a230 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
2a240 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
2a250 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
2a260 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
2a270 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2a280 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a290 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2a2a0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
2a2b0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
2a2c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
2a2d0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
2a2e0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
2a2f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2a300 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
2a310 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2a320 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2a330 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2a340 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a350 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
2a360 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
2a370 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
2a380 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
2a390 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
2a3a0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
2a3b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2a3c0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
2a3d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2a3e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2a3f0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2a400 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
2a410 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2a420 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
2a430 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
2a440 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
2a450 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
2a460 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
2a470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a480 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
2a490 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
2a4a0 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
2a4b0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
2a4c0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
2a4d0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
2a4e0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
2a4f0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
2a500 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
2a510 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
2a520 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
2a530 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
2a540 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
2a550 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
2a560 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
2a570 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2a580 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
2a590 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
2a5a0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
2a5b0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
2a5c0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
2a5d0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
2a5e0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
2a5f0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
2a600 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2a610 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
2a620 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2a630 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
2a640 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
2a650 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
2a660 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2a670 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2a680 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2a690 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2a6a0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2a6b0 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2a6c0 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2a6d0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2a6e0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2a6f0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2a700 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
2a710 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
2a720 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
2a730 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
2a740 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
2a750 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
2a760 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
2a770 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
2a780 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
2a790 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
2a7a0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
2a7b0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
2a7c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2a7d0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
2a7e0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
2a7f0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
2a800 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
2a810 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
2a820 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
2a830 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
2a840 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
2a850 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2a860 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
2a870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2a880 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2a890 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2a8a0 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
2a8b0 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
2a8c0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2a8d0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
2a8e0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
2a8f0 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
2a900 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
2a910 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
2a920 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
2a930 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
2a940 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
2a950 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2a960 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
2a970 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
2a980 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
2a990 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
2a9a0 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
2a9b0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2a9c0 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
2a9d0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2a9e0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
2a9f0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
2aa00 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
2aa10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2aa20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2aa30 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2aa40 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2aa50 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2aa60 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2aa70 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2aa80 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2aa90 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2aaa0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2aab0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2aac0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2aad0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2aae0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2aaf0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2ab00 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2ab10 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2ab20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2ab30 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2ab40 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2ab50 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2ab60 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2ab70 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2ab80 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2ab90 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2aba0 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2abb0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2abc0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2abd0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
2abe0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2abf0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
2ac00 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
2ac10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2ac20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2ac30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
2ac40 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
2ac50 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
2ac60 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
2ac70 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
2ac80 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
2ac90 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
2aca0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
2acb0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
2acc0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
2acd0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
2ace0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
2acf0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
2ad00 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
2ad10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ad20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
2ad30 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
2ad40 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2ad50 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2ad60 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
2ad70 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
2ad80 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
2ad90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ada0 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
2adb0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
2adc0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
2add0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
2ade0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2adf0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
2ae00 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2ae10 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
2ae20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2ae30 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
2ae40 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
2ae50 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
2ae60 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2ae70 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
2ae80 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2ae90 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
2aea0 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
2aeb0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2aec0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2aed0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
2aee0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
2aef0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2af00 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2af10 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2af20 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2af30 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2af40 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2af50 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2af60 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2af70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2af80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2af90 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2afa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2afb0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2afc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2afd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2afe0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2aff0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2b000 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b010 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2b020 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2b030 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2b040 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2b050 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b060 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2b070 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2b080 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2b090 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2b0a0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2b0b0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2b0c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b0d0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
2b0e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b0f0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2b100 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
2b110 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2b120 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2b130 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2b140 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
2b150 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
2b160 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b170 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2b180 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2b190 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2b1a0 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2b1b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2b1c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2b1d0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(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 2c 20 76 6f 69 64 28  oid*, int, void(
2b200 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2b210 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b220 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2b230 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2b240 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2b250 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2b260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2b270 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2b280 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2b290 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ding);.int sqlit
2b2a0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2b2b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b2c0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2b2d0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2b2e0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2b2f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2b300 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69  , int, int n);.i
2b310 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b320 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
2b330 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2b340 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
2b350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b360 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
2b370 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54  arameters.** MET
2b380 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2b390 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
2b3a0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
2b3b0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
2b3c0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
2b3d0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
2b3e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b3f0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
2b400 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
2b410 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
2b420 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
2b430 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
2b440 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
2b450 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
2b460 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
2b470 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
2b480 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2b490 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
2b4a0 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
2b4b0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
2b4c0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2b4d0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
2b4e0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2b4f0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
2b500 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
2b510 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
2b520 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
2b530 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
2b540 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
2b550 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
2b560 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
2b570 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2b580 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
2b590 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
2b5a0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
2b5b0 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
2b5c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2b5d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2b5e0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2b5f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b600 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2b610 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2b620 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b630 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2b640 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2b650 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
2b660 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2b670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b680 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
2b690 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48  arameter.** METH
2b6a0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2b6b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b6c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b6d0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2b6e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2b6f0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2b700 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2b710 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2b720 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b730 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2b740 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2b750 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2b760 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2b770 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2b780 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2b790 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2b7a0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2b7b0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2b7c0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2b7d0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2b7e0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2b7f0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2b800 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2b810 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2b820 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2b830 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2b840 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2b850 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2b860 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2b870 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2b880 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2b890 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2b8a0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2b8b0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2b8c0 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2b8d0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2b8e0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2b8f0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2b900 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2b910 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2b920 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2b930 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2b940 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2b950 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2b960 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2b970 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2b980 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2b990 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2b9a0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2b9b0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2b9c0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2b9d0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2b9e0 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2b9f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ba00 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2ba10 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ba20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2ba30 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2ba40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ba50 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2ba60 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2ba70 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ba80 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2ba90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2baa0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bab0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2bac0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2bad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2bae0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2baf0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2bb00 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
2bb10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2bb20 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2bb30 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2bb40 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2bb50 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2bb60 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
2bb70 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
2bb80 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
2bb90 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
2bba0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2bbb0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2bbc0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
2bbd0 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
2bbe0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
2bbf0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
2bc00 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
2bc10 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2bc20 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2bc30 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2bc40 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2bc50 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2bc60 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2bc70 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2bc80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2bc90 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2bca0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2bcb0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2bcc0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2bcd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2bce0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2bcf0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2bd00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2bd10 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  me()]..*/.int sq
2bd20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2bd30 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2bd40 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2bd50 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2bd60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2bd70 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2bd80 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2bd90 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
2bda0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2bdb0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
2bdc0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
2bdd0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
2bde0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
2bdf0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
2be00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2be10 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
2be20 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
2be30 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2be40 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
2be50 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
2be60 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2be70 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
2be80 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2be90 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2bea0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2beb0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2bec0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
2bed0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
2bee0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2bef0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2bf00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2bf10 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2bf20 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
2bf30 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
2bf40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2bf50 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
2bf60 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
2bf70 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
2bf80 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
2bf90 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
2bfa0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
2bfb0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
2bfc0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2bfd0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2bfe0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2bff0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2c000 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2c010 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2c020 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
2c030 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
2c040 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
2c050 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2c060 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c070 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2c080 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2c090 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2c0a0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2c0b0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2c0c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2c0d0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2c0e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2c0f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c100 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2c110 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2c120 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2c130 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2c140 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
2c150 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c160 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2c170 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
2c180 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
2c190 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2c1a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c1b0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
2c1c0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
2c1d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2c1e0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
2c1f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2c200 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
2c210 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
2c220 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
2c230 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
2c240 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2c250 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
2c260 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
2c270 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c280 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
2c290 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2c2a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2c2b0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2c2c0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2c2d0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2c2e0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2c2f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2c300 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2c310 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2c320 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2c330 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
2c340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c350 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
2c360 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2c370 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
2c380 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
2c390 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
2c3a0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
2c3b0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
2c3c0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
2c3d0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
2c3e0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
2c3f0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
2c400 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
2c410 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
2c420 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2c430 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
2c440 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2c450 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2c460 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
2c470 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
2c480 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
2c490 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
2c4a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
2c4b0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
2c4c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2c4d0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
2c4e0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
2c4f0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
2c500 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2c510 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
2c520 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2c530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c540 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c550 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
2c560 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c570 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2c580 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2c590 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c5a0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2c5b0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2c5c0 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2c5d0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c5e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2c5f0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2c600 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2c610 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2c620 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2c630 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2c640 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2c650 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2c660 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2c670 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2c680 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2c690 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2c6a0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2c6b0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2c6c0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2c6d0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2c6e0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2c6f0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2c700 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2c710 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2c720 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2c730 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2c740 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2c750 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2c760 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c770 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2c780 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2c790 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2c7a0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2c7b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c7c0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2c7d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2c7e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2c7f0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2c800 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2c810 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2c820 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2c830 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c840 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2c850 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2c860 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2c870 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2c880 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2c890 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2c8a0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2c8b0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2c8c0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2c8d0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2c8e0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2c8f0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2c900 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2c910 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2c920 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2c930 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2c940 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c950 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2c960 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2c970 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2c980 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2c990 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2c9a0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2c9b0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2c9c0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2c9d0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2c9e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2c9f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2ca00 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2ca10 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2ca20 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2ca30 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2ca40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2ca50 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2ca60 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2ca70 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2ca80 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2ca90 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2caa0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2cab0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2cac0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2cad0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2cae0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2caf0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2cb00 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2cb10 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2cb20 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2cb30 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2cb40 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2cb50 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2cb60 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2cb70 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2cb80 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2cb90 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2cba0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2cbb0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2cbc0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2cbd0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2cbe0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2cbf0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2cc00 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2cc10 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2cc20 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2cc30 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2cc40 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2cc50 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2cc60 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2cc70 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2cc80 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2cc90 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2cca0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2ccb0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2ccc0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2ccd0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2cce0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2ccf0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2cd00 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2cd10 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2cd20 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2cd30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2cd40 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2cd50 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2cd60 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2cd70 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2cd80 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2cd90 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2cda0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2cdb0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2cdc0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2cdd0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2cde0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2cdf0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2ce00 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2ce10 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2ce20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2ce30 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2ce40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2ce50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2ce60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2ce70 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
2ce80 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ce90 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2cea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2ceb0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2cec0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2ced0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2cee0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
2cef0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2cf00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2cf10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2cf20 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2cf30 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2cf40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2cf50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2cf60 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2cf70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2cf80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2cf90 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2cfa0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2cfb0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
2cfc0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2cfd0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
2cfe0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
2cff0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d000 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
2d010 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
2d020 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
2d030 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
2d040 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
2d050 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
2d060 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
2d070 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
2d080 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
2d090 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2d0a0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
2d0b0 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
2d0c0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
2d0d0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
2d0e0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
2d0f0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2d100 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
2d110 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2d120 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
2d130 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2d140 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
2d150 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2d160 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
2d170 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
2d180 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2d190 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
2d1a0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
2d1b0 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
2d1c0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
2d1d0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
2d1e0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
2d1f0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
2d200 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
2d210 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
2d220 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
2d230 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
2d240 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
2d250 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
2d260 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
2d270 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
2d280 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
2d290 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
2d2a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
2d2b0 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
2d2c0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2d2d0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
2d2e0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
2d2f0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
2d300 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
2d310 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
2d320 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
2d330 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
2d340 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
2d350 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
2d360 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
2d370 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
2d380 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
2d390 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
2d3a0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
2d3b0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
2d3c0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
2d3d0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
2d3e0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
2d3f0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
2d400 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
2d410 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
2d420 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
2d430 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d440 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2d450 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2d460 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2d470 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2d480 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2d490 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2d4a0 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2d4b0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2d4c0 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2d4d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2d4e0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2d4f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2d500 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2d510 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2d520 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d530 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2d540 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2d550 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2d560 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2d570 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2d580 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2d590 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2d5a0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2d5b0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2d5c0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2d5d0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2d5e0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2d5f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2d600 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2d610 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2d620 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2d630 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2d640 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2d650 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2d660 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2d670 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2d680 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2d690 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2d6a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d6b0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2d6c0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2d6d0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2d6e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2d6f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2d700 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2d710 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2d720 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2d730 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2d740 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2d750 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2d760 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2d770 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2d780 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2d790 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2d7a0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2d7b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2d7c0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2d7d0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2d7e0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2d7f0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2d800 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2d810 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2d820 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2d830 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2d840 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2d850 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2d860 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2d870 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2d880 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2d890 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2d8a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2d8b0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2d8c0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2d8d0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2d8e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2d8f0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2d900 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2d910 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2d920 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2d930 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2d940 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2d950 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2d960 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2d970 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2d980 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2d990 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2d9a0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2d9b0 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2d9c0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2d9d0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2d9e0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2d9f0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2da00 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2da10 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2da20 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2da30 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2da40 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2da50 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2da60 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2da70 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2da80 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2da90 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2daa0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2dab0 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2dac0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2dad0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2dae0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2daf0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2db00 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2db10 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2db20 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2db30 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2db40 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2db50 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2db60 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2db70 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2db80 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2db90 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2dba0 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2dbb0 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2dbc0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2dbd0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2dbe0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2dbf0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2dc00 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2dc10 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2dc20 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2dc30 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2dc40 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2dc50 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2dc60 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2dc70 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2dc80 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2dc90 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2dca0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2dcb0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2dcc0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2dcd0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2dce0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2dcf0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2dd00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2dd10 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2dd20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2dd30 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2dd40 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2dd50 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2dd60 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2dd70 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2dd80 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2dd90 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2dda0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2ddb0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2ddc0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2ddd0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2dde0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ddf0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2de00 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2de10 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2de20 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2de30 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2de40 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2de50 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2de60 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2de70 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2de80 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2de90 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2dea0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2deb0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2dec0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2ded0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2dee0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2def0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2df00 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2df10 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2df20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2df30 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2df40 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2df50 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2df60 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2df70 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2df80 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2df90 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2dfa0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2dfb0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2dfc0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2dfd0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2dfe0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2dff0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2e000 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2e010 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2e020 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e030 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2e040 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2e050 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2e060 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2e070 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2e080 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2e090 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2e0a0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2e0b0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2e0c0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2e0d0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2e0e0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2e0f0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2e100 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2e110 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2e120 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2e130 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2e140 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2e150 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2e160 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2e170 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2e180 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2e190 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2e1a0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2e1b0 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2e1c0 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2e1d0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2e1e0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2e1f0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2e200 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2e210 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2e220 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2e230 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2e240 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2e250 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2e260 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2e270 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2e280 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2e290 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2e2a0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2e2b0 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2e2c0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2e2d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2e2e0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2e2f0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2e300 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2e310 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2e320 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2e330 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2e340 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2e350 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2e360 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2e370 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2e380 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2e390 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2e3a0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2e3b0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2e3c0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2e3d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2e3e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2e3f0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2e400 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2e410 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2e420 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2e430 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2e440 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2e450 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2e460 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2e470 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2e480 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2e490 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2e4a0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2e4b0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2e4c0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2e4d0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2e4e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2e4f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e500 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2e510 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2e520 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e530 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2e540 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2e550 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2e560 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2e570 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2e580 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2e590 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2e5a0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2e5b0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2e5c0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2e5d0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2e5e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2e5f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e610 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2e620 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2e630 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2e640 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e650 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2e660 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2e670 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2e680 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2e690 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2e6a0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2e6b0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2e6c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e6d0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2e6e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e6f0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2e700 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2e710 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2e720 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2e730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2e740 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2e750 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2e760 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2e770 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2e780 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2e790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e7a0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2e7b0 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2e7c0 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2e7d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2e7e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2e7f0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2e800 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2e810 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2e820 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2e830 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2e840 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2e850 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2e860 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2e870 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2e880 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2e890 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2e8a0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2e8b0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2e8c0 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2e8d0 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2e8e0 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2e8f0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2e900 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2e910 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2e920 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2e930 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2e940 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2e950 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2e960 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2e970 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2e980 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2e990 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
2e9a0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2e9b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2e9c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2e9d0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2e9e0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2e9f0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2ea00 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2ea10 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2ea20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2ea30 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2ea40 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2ea50 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2ea60 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2ea70 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2ea80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2ea90 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2eaa0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2eab0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2eac0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2ead0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2eae0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2eaf0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2eb00 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2eb10 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2eb20 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2eb30 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2eb40 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2eb50 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2eb60 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2eb70 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2eb80 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2eb90 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2eba0 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2ebb0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2ebc0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2ebd0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2ebe0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2ebf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2ec00 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2ec10 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2ec20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2ec30 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2ec40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2ec50 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2ec60 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2ec70 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2ec80 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2ec90 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2eca0 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2ecb0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2ecc0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2ecd0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2ece0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2ecf0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2ed00 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2ed10 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
2ed20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2ed30 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2ed40 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2ed50 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2ed60 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2ed70 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2ed80 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2ed90 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2eda0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2edb0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2edc0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2edd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ede0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2edf0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2ee00 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2ee10 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2ee20 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2ee30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2ee40 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2ee50 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2ee60 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2ee70 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2ee80 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2ee90 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2eea0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2eeb0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2eec0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2eed0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2eee0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2eef0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2ef00 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2ef10 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2ef20 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2ef30 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2ef40 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2ef50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2ef60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2ef70 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2ef80 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2ef90 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2efa0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2efb0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2efc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2efd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2efe0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2eff0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2f000 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2f010 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2f020 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f030 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2f040 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2f050 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2f060 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2f070 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f080 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2f090 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2f0a0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2f0b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2f0c0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2f0d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f0e0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2f0f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2f100 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2f110 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2f120 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2f130 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2f140 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2f150 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2f160 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2f170 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2f180 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f190 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2f1a0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2f1b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2f1c0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2f1d0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2f1e0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2f1f0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2f200 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2f210 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2f220 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2f230 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2f240 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2f250 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2f260 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2f270 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2f280 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2f290 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2f2a0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2f2b0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2f2c0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2f2d0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2f2e0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2f2f0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2f300 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2f310 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2f320 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2f330 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f340 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2f350 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2f360 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2f370 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2f380 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2f390 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2f3a0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f3b0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2f3c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2f3d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2f3e0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2f3f0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2f400 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2f410 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2f420 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2f430 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2f440 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2f450 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2f460 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2f470 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2f480 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2f490 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2f4a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2f4b0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2f4c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f4d0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2f4e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2f4f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2f500 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2f510 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2f520 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2f530 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2f540 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2f550 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2f560 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2f570 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2f580 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2f590 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2f5a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f5b0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2f5c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2f5d0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2f5e0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2f5f0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2f600 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2f610 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f620 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2f630 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f640 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2f650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f660 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2f670 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2f680 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2f690 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2f6a0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2f6b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f6c0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2f6d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2f6e0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2f6f0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2f700 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2f710 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2f720 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2f730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f740 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2f750 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2f760 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2f770 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2f780 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2f790 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f7a0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2f7b0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2f7c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2f7d0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2f7e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2f7f0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2f800 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2f810 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2f820 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2f830 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2f840 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2f850 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f860 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2f870 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f880 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2f890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2f8a0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2f8b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f8c0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2f8d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f8e0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2f8f0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2f900 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2f910 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2f920 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2f930 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2f940 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2f950 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2f960 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2f970 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2f980 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2f990 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2f9a0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2f9b0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2f9c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2f9d0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2f9e0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2f9f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa00 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2fa10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2fa20 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2fa30 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2fa40 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2fa50 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2fa60 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2fa70 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2fa80 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2fa90 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2faa0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2fab0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
2fac0 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
2fad0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2fae0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2faf0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2fb00 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2fb10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2fb20 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
2fb30 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
2fb40 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
2fb50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fb60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
2fb70 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
2fb80 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
2fb90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2fba0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2fbb0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2fbc0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2fbd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2fbe0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2fbf0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2fc00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2fc10 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2fc20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2fc30 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2fc40 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2fc50 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2fc60 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2fc70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2fc80 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2fc90 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2fca0 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
2fcb0 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
2fcc0 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  fe..**.** These 
2fcd0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2fce0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2fcf0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2fd00 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2fd10 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2fd20 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2fd30 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2fd40 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2fd50 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2fd60 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2fd70 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2fd80 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2fd90 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2fda0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2fdb0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2fdc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2fdd0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2fde0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2fdf0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2fe00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2fe10 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2fe20 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2fe30 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2fe40 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2fe50 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2fe60 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2fe70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2fe80 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2fe90 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2fea0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2feb0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2fec0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2fed0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2fee0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2fef0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2ff00 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2ff10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2ff20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2ff30 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2ff40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2ff50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2ff60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2ff70 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2ff80 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2ff90 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2ffa0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2ffb0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2ffc0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2ffd0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2ffe0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2fff0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
30000 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
30010 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
30020 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
30030 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
30040 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30050 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30060 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
30070 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
30080 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
30090 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
300a0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
300b0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
300c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
300d0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
300e0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
300f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
30100 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
30110 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
30120 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
30130 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
30140 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
30150 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
30160 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
30170 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
30180 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
30190 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
301a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
301b0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
301c0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
301d0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
301e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
301f0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
30200 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
30210 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
30220 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
30230 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
30240 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
30250 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
30260 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ote>)^.**.** Not
30270 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
30280 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
30290 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
302a0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
302b0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
302c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
302d0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
302e0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
302f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30300 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
30310 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
30320 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
30330 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
30340 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
30350 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
30360 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
30370 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
30380 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
30390 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
303a0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
303b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
303c0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
303d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
303e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
303f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
30400 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
30410 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
30420 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
30430 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
30440 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30450 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
30460 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30470 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
30480 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
30490 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
304a0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
304b0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
304c0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
304d0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
304e0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
304f0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
30500 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
30510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30520 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
30530 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30540 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
30550 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
30560 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
30570 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
30580 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
30590 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
305a0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
305b0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
305c0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
305d0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
305e0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
305f0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
30600 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
30610 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
30620 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
30630 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
30640 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
30650 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
30660 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
30670 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
30680 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
30690 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
306a0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
306b0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
306c0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
306d0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
306e0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
306f0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
30700 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
30710 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c  * The safest pol
30720 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
30730 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
30740 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
30750 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
30760 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
30770 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
30780 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
30790 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
307a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
307b0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
307c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
307d0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
307e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
307f0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
30800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30810 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
30820 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30830 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
30840 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
30850 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
30860 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
30870 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30880 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
30890 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
308a0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
308b0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
308c0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
308d0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
308e0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
308f0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
30900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30910 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
30920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30930 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
30940 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
30950 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
30960 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
30970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30980 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
30990 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
309a0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
309b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
309c0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
309d0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
309e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
309f0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
30a00 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
30a10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
30a20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
30a30 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
30a40 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
30a50 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
30a60 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
30a70 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
30a80 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
30a90 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
30aa0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
30ab0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
30ac0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
30ad0 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
30ae0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
30af0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
30b00 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
30b10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
30b20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  Do <em>not</em> 
30b30 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
30b40 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
30b50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
30b60 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
30b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30b80 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
30b90 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
30ba0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
30bb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
30bc0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
30bd0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
30be0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
30bf0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
30c00 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
30c10 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
30c20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
30c30 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
30c40 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
30c50 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
30c60 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
30c70 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
30c80 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
30c90 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
30ca0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
30cb0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
30cc0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
30cd0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30cf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30d00 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
30d10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30d20 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
30d30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
30d40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
30d50 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
30d60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30d70 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
30d80 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
30d90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30da0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
30db0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
30dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30dd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
30de0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
30df0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
30e00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30e10 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
30e20 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
30e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30e40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30e50 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
30e60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
30e70 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
30e80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30e90 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
30ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
30eb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30ec0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
30ed0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
30ee0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
30ef0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30f00 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
30f10 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
30f20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
30f30 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
30f40 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
30f50 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
30f60 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
30f70 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
30f80 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
30f90 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
30fa0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
30fb0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
30fc0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
30fd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
30fe0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
30ff0 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
31000 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
31010 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
31020 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
31030 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
31040 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
31050 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
31060 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
31070 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
31080 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
31090 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
310a0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
310b0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
310c0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
310d0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
310e0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
310f0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
31100 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
31110 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
31120 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
31130 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
31140 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
31150 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
31160 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
31170 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
31180 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
31190 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
311a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
311b0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
311c0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
311d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
311e0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
311f0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
31200 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
31210 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
31220 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
31230 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
31240 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
31250 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
31260 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
31270 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
31280 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
31290 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
312a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
312b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
312c0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
312d0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
312e0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
312f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31300 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
31310 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
31320 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
31330 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
31340 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
31350 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
31360 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
31370 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
31380 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
31390 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
313a0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
313b0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
313c0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
313d0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
313e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
313f0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
31400 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
31410 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
31420 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
31430 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
31440 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
31450 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
31460 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
31470 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
31480 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
31490 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
314a0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
314b0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
314c0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
314d0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
314e0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
314f0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
31500 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
31510 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
31520 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
31530 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31540 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
31550 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
31560 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
31570 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
31580 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
31590 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
315a0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
315b0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
315c0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
315d0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
315e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
315f0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
31600 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
31610 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
31620 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
31630 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
31640 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
31650 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
31660 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
31670 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
31680 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
31690 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
316a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
316b0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
316c0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
316d0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
316e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
316f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
31700 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
31710 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
31720 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31730 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
31740 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
31750 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
31760 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
31770 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
31780 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
31790 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
317a0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
317b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
317c0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
317d0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
317e0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
317f0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
31800 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
31810 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
31820 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31830 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
31840 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
31850 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31860 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31870 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
31880 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
31890 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
318a0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
318b0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
318c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
318d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
318e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
318f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
31900 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31910 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
31920 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31930 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
31940 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
31950 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
31960 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
31970 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
31980 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
31990 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
319a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
319b0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
319c0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
319d0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
319e0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
319f0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
31a00 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
31a10 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
31a20 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
31a30 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
31a40 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
31a50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
31a60 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
31a70 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
31a80 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
31a90 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
31aa0 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
31ab0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
31ac0 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
31ad0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
31ae0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
31af0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
31b00 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
31b10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31b20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
31b30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
31b40 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
31b50 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
31b60 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
31b70 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
31b80 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
31b90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31ba0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
31bb0 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
31bc0 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
31bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
31be0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
31bf0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
31c00 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
31c10 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
31c20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
31c30 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
31c40 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
31c50 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
31c60 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
31c70 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
31c80 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
31c90 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
31ca0 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
31cb0 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
31cc0 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
31cd0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
31ce0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
31cf0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
31d00 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
31d10 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
31d20 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
31d30 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
31d40 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
31d50 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
31d60 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
31d70 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
31d80 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
31d90 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
31da0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
31db0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
31dc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31dd0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
31de0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
31df0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
31e00 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
31e10 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
31e20 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
31e30 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
31e40 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
31e50 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
31e60 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
31e70 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
31e80 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
31e90 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
31ea0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
31eb0 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
31ec0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
31ed0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
31ee0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
31ef0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
31f00 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
31f10 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
31f20 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
31f30 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
31f40 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
31f50 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
31f60 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
31f70 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
31f80 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
31f90 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
31fa0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
31fb0 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
31fc0 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
31fd0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
31fe0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
31ff0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32000 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
32010 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
32020 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
32030 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
32040 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
32050 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32060 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
32070 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
32080 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
32090 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
320a0 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
320b0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
320c0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
320d0 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
320e0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
320f0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
32100 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
32110 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
32120 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
32130 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
32140 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
32150 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
32160 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
32170 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
32180 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
32190 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
321a0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
321b0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
321c0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
321d0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
321e0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
321f0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
32200 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
32210 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
32220 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
32230 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
32240 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
32250 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
32260 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
32270 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
32280 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
32290 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
322a0 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
322b0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
322c0 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
322d0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
322e0 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
322f0 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
32300 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
32310 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
32320 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
32330 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
32340 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
32350 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
32360 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
32370 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
32380 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
32390 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
323a0 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
323b0 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
323c0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
323d0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
323e0 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
323f0 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
32400 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
32410 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
32420 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
32430 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
32440 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
32450 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
32460 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
32470 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
32480 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
32490 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
324a0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
324b0 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
324c0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
324d0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
324e0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
324f0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
32500 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
32510 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
32520 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32530 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
32540 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
32550 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
32560 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
32570 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
32580 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
32590 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
325a0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
325b0 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
325c0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
325d0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
325e0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
325f0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
32600 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
32610 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
32620 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
32630 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
32640 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
32650 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
32660 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
32670 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
32680 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
32690 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
326a0 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
326b0 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
326c0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
326d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
326e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
326f0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
32700 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
32710 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
32720 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
32730 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
32740 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
32750 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
32760 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
32770 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
32780 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
32790 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
327a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
327b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
327c0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
327d0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
327e0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
327f0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
32800 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32810 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
32820 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
32830 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
32840 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
32850 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
32860 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
32870 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
32880 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
32890 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
328a0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
328b0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
328c0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
328d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
328e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
328f0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
32900 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
32910 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
32920 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
32930 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
32940 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
32950 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
32960 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
32970 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
32980 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
32990 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
329a0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
329b0 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
329c0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
329d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
329e0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
329f0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
32a00 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
32a10 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
32a20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
32a30 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
32a40 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
32a50 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
32a60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
32a70 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
32a80 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
32a90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
32aa0 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
32ab0 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
32ac0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
32ad0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
32ae0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
32af0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
32b00 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
32b10 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
32b20 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
32b30 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
32b40 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
32b50 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
32b60 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
32b70 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
32b80 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
32b90 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
32ba0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
32bb0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
32bc0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
32bd0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
32be0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
32bf0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
32c00 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
32c10 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
32c20 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
32c30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32c40 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
32c50 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
32c60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32c70 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
32c80 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
32c90 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
32ca0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
32cb0 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
32cc0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
32cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32ce0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
32cf0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
32d00 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
32d10 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
32d20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
32d30 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
32d40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32d50 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
32d60 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
32d70 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
32d80 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
32d90 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
32da0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
32db0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
32dc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
32dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
32de0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
32df0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32e00 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32e10 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32e20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
32e30 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
32e40 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32e50 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
32e60 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
32e70 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
32e80 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
32e90 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
32ea0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
32eb0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
32ec0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
32ed0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
32ee0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
32ef0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
32f00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
32f10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
32f20 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
32f30 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
32f40 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
32f50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32f60 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
32f70 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
32f80 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
32f90 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
32fa0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
32fb0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
32fc0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
32fd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
32fe0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32ff0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
33000 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
33010 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33020 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33030 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
33040 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
33050 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
33060 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
33070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
33080 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
33090 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
330a0 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
330b0 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
330c0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
330d0 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
330e0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
330f0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
33100 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
33110 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a           1    /*
33120 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35   IMP: R-37514-35
33130 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  566 */.#define S
33140 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
33150 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50       2    /* IMP
33160 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20  : R-03371-37637 
33170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33180 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
33190 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   3    /* IMP: R-
331a0 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23  51971-34154 */.#
331b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
331c0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
331d0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
331e0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
331f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
33200 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
33210 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a   /* Deprecated *
33220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33230 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
33240 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
33250 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33260 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
33270 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
33280 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  on Flags.**.** T
33290 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d  hese constants m
332a0 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74  ay be ORed toget
332b0 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  her with the .**
332c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
332d0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
332e0 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20  ncoding] as the 
332f0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
33300 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
33310 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
33320 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
33330 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33340 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33350 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33360 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _v2()]..*/.#defi
33370 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  ne SQLITE_DETERM
33380 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30  INISTIC    0x800
33390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
333a0 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
333b0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
333c0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
333d0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
333e0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
333f0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
33400 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
33410 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
33420 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
33430 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
33440 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
33450 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
33460 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
33470 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
33480 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
33490 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
334a0 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67  ns.  To encourag
334b0 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f  e programmers to
334c0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20   avoid.** these 
334d0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69  functions, we wi
334e0 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77  ll not explain w
334f0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
33500 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
33510 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
33520 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
33530 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
33540 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
33550 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33560 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33570 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
33580 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
33590 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
335a0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
335b0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
335c0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
335d0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
335e0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
335f0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
33600 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
33610 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
33620 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
33630 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
33640 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
33650 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33660 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
33670 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
33680 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
33690 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
336a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
336b0 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
336c0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
336d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
336e0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c  btaining SQL Val
336f0 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
33700 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
33710 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
33720 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33730 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
33740 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
33750 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
33760 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
33770 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
33780 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
33790 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
337a0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
337b0 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20  regate.  .**.** 
337c0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
337d0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
337e0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
337f0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
33800 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
33810 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33820 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
33830 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33840 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
33850 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
33860 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
33870 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
33880 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
33890 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
338a0 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
338b0 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
338c0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
338d0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
338e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
338f0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
33900 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
33910 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
33920 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
33930 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
33940 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
33950 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
33960 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
33970 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
33980 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33990 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
339a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
339b0 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
339c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
339d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
339e0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
339f0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
33a00 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
33a10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33a20 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
33a30 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
33a40 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
33a50 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
33a60 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
33a70 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
33a80 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
33a90 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
33aa0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74  ** except that t
33ab0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
33ac0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
33ad0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33ae0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
33af0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
33b00 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
33b10 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
33b20 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
33b30 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
33b40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
33b50 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
33b60 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
33b70 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
33b80 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
33b90 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
33ba0 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
33bb0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
33bc0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
33bd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
33be0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
33bf0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
33c00 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
33c10 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
33c20 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
33c30 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
33c40 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
33c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
33c60 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
33c70 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
33c80 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
33c90 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
33ca0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
33cb0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
33cc0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
33cd0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
33ce0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
33cf0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
33d00 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
33d10 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
33d20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
33d30 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
33d40 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
33d50 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
33d60 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
33d70 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
33d80 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
33d90 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
33da0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
33db0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
33dc0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
33dd0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
33de0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
33df0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
33e00 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
33e10 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
33e20 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
33e30 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
33e40 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
33e50 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
33e60 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
33e70 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
33e80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
33e90 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
33ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
33eb0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
33ec0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
33ed0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
33ee0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
33ef0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
33f00 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
33f10 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
33f20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33f30 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
33f40 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33f50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
33f60 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
33f70 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33f80 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
33f90 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
33fa0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
33fb0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
33fc0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
33fd0 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
33fe0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
33ff0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
34000 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
34010 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
34020 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34030 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
34040 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
34050 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
34060 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
34070 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
34080 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
34090 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
340a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
340b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
340c0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
340d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
340e0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
340f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
34100 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
34110 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
34120 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
34130 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
34140 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
34150 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
34160 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
34170 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34180 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34190 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
341a0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
341b0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
341c0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(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 6e   sqlite3_value_n
341f0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
34200 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
34210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
34220 6e 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70  nding The Subtyp
34230 65 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a  e Of SQL Values.
34240 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
34250 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54  e3_value.**.** T
34260 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
34270 5f 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63  _subtype(V) func
34280 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
34290 20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20   subtype for.** 
342a0 61 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  an [application-
342b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
342c0 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56  tion] argument V
342d0 2e 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a  .  The subtype.*
342e0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61  * information ca
342f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73  n be used to pas
34300 73 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75  s a limited amou
34310 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72  nt of context fr
34320 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75  om.** one SQL fu
34330 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65  nction to anothe
34340 72 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c  r.  Use the [sql
34350 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74  ite3_result_subt
34360 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  ype()].** routin
34370 65 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62  e to set the sub
34380 74 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74  type for the ret
34390 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  urn value of an 
343a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
343b0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
343c0 20 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79   no use of subty
343d0 70 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d  pe itself.  It m
343e0 65 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65  erely passes the
343f0 20 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d   subtype.** from
34400 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f   the result of o
34410 6e 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ne [application-
34420 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
34430 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a  tion] into the.*
34440 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68  * input of anoth
34450 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20  er..*/.unsigned 
34460 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
34470 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65  e_subtype(sqlite
34480 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
34490 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79  * CAPI3REF: Copy
344a0 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61   And Free SQL Va
344b0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
344c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
344d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
344e0 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e  _value_dup(V) in
344f0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
34500 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
34510 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
34520 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75  bject D and retu
34530 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
34540 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68   that copy.  ^Th
34550 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34560 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  ] returned.** is
34570 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   a [protected sq
34580 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34590 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20  ect even if the 
345a0 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a  input is not..**
345b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
345c0 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
345d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
345e0 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f  L if V is NULL o
345f0 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79  r if a.** memory
34600 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
34610 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
34620 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
34630 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72  (V) interface fr
34640 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ees an [sqlite3_
34650 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
34660 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
34670 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
34680 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
34690 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c    ^If V is a NUL
346a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  L pointer.** the
346b0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  n sqlite3_value_
346c0 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72  free(V) is a har
346d0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
346e0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
346f0 54 41 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  TAL sqlite3_valu
34700 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e *sqlite3_value
34710 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74  _dup(const sqlit
34720 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34730 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
34740 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  void sqlite3_val
34750 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ue_free(sqlite3_
34760 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
34770 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
34780 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
34790 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d  ion Context.** M
347a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
347b0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
347c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
347d0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
347e0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
347f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
34800 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
34810 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
34820 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
34830 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
34840 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
34850 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
34860 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
34870 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
34880 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
34890 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
348a0 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
348b0 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
348c0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
348d0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
348e0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
348f0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
34900 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
34910 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
34920 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
34930 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34940 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
34950 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
34960 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
34970 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
34980 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
34990 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
349a0 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
349b0 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
349c0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
349d0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
349e0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
349f0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
34a00 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
34a10 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
34a20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
34a30 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
34a40 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
34a50 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
34a60 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
34a70 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
34a80 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
34a90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
34aa0 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
34ab0 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
34ac0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
34ad0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
34ae0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
34af0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
34b00 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
34b10 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
34b20 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
34b30 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
34b40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34b50 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34b60 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
34b70 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
34b80 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20  ointer .** when 
34b90 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20  first called if 
34ba0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
34bb0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
34bc0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a  or if a memory.*
34bd0 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  * allocate error
34be0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
34bf0 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
34c00 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
34c10 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
34c20 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
34c30 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
34c40 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
34c50 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
34c60 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
34c70 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
34c80 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
34c90 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
34ca0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34cb0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
34cc0 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
34cd0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
34ce0 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
34cf0 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
34d00 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
34d10 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20  tion.)^  Within 
34d20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
34d30 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f  ack, it is custo
34d40 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e  mary to set.** N
34d50 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73  =0 in calls to s
34d60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34d70 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f  _context(C,N) so
34d80 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69   that no .** poi
34d90 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c  ntless memory al
34da0 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e  locations occur.
34db0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
34dc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
34dd0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
34de0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
34df0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34e00 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
34e10 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
34e20 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
34e30 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
34e40 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
34e50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
34e60 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
34e70 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
34e80 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
34e90 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
34ea0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
34eb0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
34ec0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
34ed0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
34ee0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
34ef0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
34f00 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34f10 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
34f20 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
34f30 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
34f40 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
34f50 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
34f60 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
34f70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34f80 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
34f90 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34fa0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
34fb0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
34fc0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
34fd0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
34fe0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
34ff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35000 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
35010 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35020 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
35030 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
35040 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
35050 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
35060 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
35070 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
35080 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
35090 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
350a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
350b0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
350c0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
350d0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
350e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
350f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
35100 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
35110 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
35120 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
35130 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
35140 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
35150 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35160 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
35170 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
35180 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
35190 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
351a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
351b0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
351c0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
351d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
351e0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
351f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
35200 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
35210 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35220 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
35230 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
35240 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35250 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
35260 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
35270 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
35280 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35290 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
352a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
352b0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
352c0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
352d0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
352e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
352f0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
35300 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  n..*/.sqlite3 *s
35310 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
35320 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
35330 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
35340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
35350 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
35360 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Data.** METHOD: 
35370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
35380 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
35390 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
353a0 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67  d by (non-aggreg
353b0 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ate) SQL functio
353c0 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
353d0 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
353e0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
353f0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
35400 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
35410 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
35420 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
35430 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
35440 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
35450 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
35460 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
35470 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
35480 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
35490 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
354a0 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f   An example.** o
354b0 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67  f where this mig
354c0 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20  ht be useful is 
354d0 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  in a regular-exp
354e0 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
354f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
35500 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
35510 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
35520 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
35530 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   be stored as.**
35540 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
35550 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61  ated with the pa
35560 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a  ttern string.  .
35570 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20  ** Then as long 
35580 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  as the pattern s
35590 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68  tring remains th
355a0 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63  e same,.** the c
355b0 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
355c0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
355d0 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
355e0 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
355f0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
35600 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
35610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
35620 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
35630 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
35640 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
35650 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
35660 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
35670 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35680 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
35690 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
356a0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
356b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
356c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
356d0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
356e0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
356f0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66  iated with the f
35700 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
35710 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67  , this sqlite3_g
35720 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
35730 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
35740 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35750 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35760 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35770 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66  (C,N,P,X) interf
35780 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d  ace saves P as m
35790 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
357a0 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
357b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
357c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
357d0 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65  tion.  ^Subseque
357e0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
357f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
35800 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50  ta(C,N) return P
35810 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72   from the most r
35820 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33  ecent.** sqlite3
35830 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
35840 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68  ,P,X) call if th
35850 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74  e metadata is st
35860 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20  ill valid or.** 
35870 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61  NULL if the meta
35880 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69  data has been di
35890 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74  scarded..** ^Aft
358a0 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20  er each call to 
358b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
358c0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65  ata(C,N,P,X) whe
358d0 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  re X is not NULL
358e0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ,.** SQLite will
358f0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
35900 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
35910 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72  X with parameter
35920 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e   P exactly.** on
35930 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74  ce, when the met
35940 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64  adata is discard
35950 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  ed..** SQLite is
35960 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64   free to discard
35970 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74   the metadata at
35980 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75   any time, inclu
35990 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  ding: <ul>.** <l
359a0 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  i> when the corr
359b0 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
359c0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
359d0 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  nges, or.** <li>
359e0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   when [sqlite3_r
359f0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
35a00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
35a10 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  is called for th
35a20 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74  e.**      SQL st
35a30 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c  atement, or.** <
35a40 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33  li> when sqlite3
35a50 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
35a60 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20  s invoked again 
35a70 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61  on the same para
35a80 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  meter, or.** <li
35a90 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69  > during the ori
35aa0 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65  ginal sqlite3_se
35ab0 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c  t_auxdata() call
35ac0 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a   when a memory .
35ad0 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69  **      allocati
35ae0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  on error occurs.
35af0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e   </ul>)^.**.** N
35b00 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c  ote the last bul
35b10 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61  let in particula
35b20 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  r.  The destruct
35b30 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69  or X in .** sqli
35b40 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35b50 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62  C,N,P,X) might b
35b60 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61  e called immedia
35b70 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65  tely, before the
35b80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
35b90 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
35ba0 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73  ace even returns
35bb0 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33  .  Hence sqlite3
35bc0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a  _set_auxdata().*
35bd0 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c  * should be call
35be0 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20  ed near the end 
35bf0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
35c00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
35c10 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  nd the.** functi
35c20 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
35c30 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b  n should not mak
35c40 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61  e any use of P a
35c50 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  fter.** sqlite3_
35c60 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61  set_auxdata() ha
35c70 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  s been called..*
35c80 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
35c90 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
35ca0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
35cb0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
35cc0 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   for.** function
35cd0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
35ce0 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   are compile-tim
35cf0 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63  e constants, inc
35d00 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a  luding literal.*
35d10 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
35d20 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78  rameters] and ex
35d30 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73  pressions compos
35d40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
35d50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
35d60 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
35d70 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
35d80 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
35d90 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
35da0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
35db0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
35dc0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
35dd0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
35de0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
35df0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
35e00 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
35e10 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
35e20 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
35e30 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
35e40 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
35e50 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
35e60 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
35e70 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
35e80 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
35e90 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
35ea0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
35eb0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
35ec0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
35ed0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
35ee0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
35ef0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
35f00 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
35f10 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
35f20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
35f30 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
35f40 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
35f50 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
35f60 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
35f70 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
35f80 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
35f90 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
35fa0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
35fb0 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
35fc0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
35fd0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
35fe0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
35ff0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
36000 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
36010 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
36020 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
36030 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
36040 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
36050 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
36060 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
36070 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
36080 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
36090 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
360a0 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  lers..*/.typedef
360b0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
360c0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
360d0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
360e0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
360f0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
36100 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
36110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
36120 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
36130 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
36140 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
36150 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
36160 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
36170 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
36180 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36190 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
361a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
361b0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
361c0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
361d0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
361e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
361f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
36200 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
36210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
36220 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
36230 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
36240 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
36250 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
36260 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
36270 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
36280 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
36290 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
362a0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
362b0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
362c0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
362d0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
362e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
362f0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
36300 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
36310 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
36320 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
36330 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
36340 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
36350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36360 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36370 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36380 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
36390 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
363a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
363b0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
363c0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
363d0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
363e0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
363f0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
36400 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
36410 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
36420 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
36430 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
36440 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36450 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20  t_zeroblob(C,N) 
36460 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
36470 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c  lt_zeroblob64(C,
36480 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  N).** interfaces
36490 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
364a0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
364b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
364c0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42  ion to be.** a B
364d0 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
364e0 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e  ll zero bytes an
364f0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
36500 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
36510 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
36520 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
36530 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
36540 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
36550 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36560 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
36570 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
36580 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
36590 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
365a0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
365b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
365c0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
365d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
365e0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
365f0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
36600 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
36610 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
36620 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
36630 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
36640 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
36650 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
36660 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
36670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36680 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
36690 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
366a0 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
366b0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
366c0 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
366d0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
366e0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
366f0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
36700 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
36710 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
36720 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
36730 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
36740 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36750 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
36760 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
36770 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
36780 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
36790 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
367a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
367b0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
367c0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
367d0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
367e0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
367f0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
36800 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
36810 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
36820 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
36830 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
36840 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
36850 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36860 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
36870 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36880 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
36890 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
368a0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
368b0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
368c0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
368d0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
368e0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
368f0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
36900 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36910 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
36920 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36930 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
36940 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
36950 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
36960 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
36970 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
36980 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
36990 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
369a0 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
369b0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
369c0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
369d0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
369e0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
369f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36a00 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
36a10 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
36a20 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
36a30 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
36a40 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
36a50 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
36a60 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
36a70 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
36a80 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
36a90 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
36aa0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
36ab0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
36ac0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
36ad0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36ae0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
36af0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
36b00 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
36b10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36b20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
36b30 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
36b40 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
36b50 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
36b60 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
36b70 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
36b80 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
36b90 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
36ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36bb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36bc0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
36bd0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
36be0 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
36bf0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
36c00 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
36c10 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
36c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36c30 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
36c40 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
36c50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36c60 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
36c70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36c80 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
36c90 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
36ca0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
36cb0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
36cc0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
36cd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36ce0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
36cf0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36d00 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
36d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36d20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36d30 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
36d40 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
36d50 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
36d60 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
36d70 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
36d80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36d90 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
36da0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
36db0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
36dc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36dd0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36de0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
36df0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36e00 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
36e10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
36e20 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
36e30 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
36e40 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
36e50 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
36e60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
36e70 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
36e80 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
36e90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36ea0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
36eb0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
36ec0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
36ed0 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
36ee0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
36ef0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
36f00 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
36f10 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
36f20 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
36f30 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ely..** ^The sql
36f40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36f50 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
36f60 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36f70 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70  alue of an.** ap
36f80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36f90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
36fa0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69   a text string i
36fb0 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  n an encoding.**
36fc0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
36fd0 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73  e fifth (and las
36fe0 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  t) parameter, wh
36ff0 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a  ich must be one.
37000 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ** of [SQLITE_UT
37010 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
37020 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
37030 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
37040 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e  E_UTF16LE]..** ^
37050 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
37060 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
37070 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
37080 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
37090 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
370a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
370b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
370c0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
370d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
370e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
370f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
37100 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
37110 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
37120 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
37130 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
37140 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
37150 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
37160 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
37170 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
37180 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
37190 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
371a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
371b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
371c0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
371d0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
371e0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
371f0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
37200 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
37210 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
37220 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
37230 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
37240 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
37250 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
37260 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
37270 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
37280 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
37290 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
372a0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
372b0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
372c0 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
372d0 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
372e0 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
372f0 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
37300 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
37310 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
37320 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
37330 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
37340 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
37350 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
37360 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
37370 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
37380 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
37390 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
373a0 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
373b0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
373c0 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
373d0 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
373e0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
373f0 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
37400 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
37410 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
37420 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
37430 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
37440 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
37450 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
37460 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
37470 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
37480 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
37490 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
374a0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
374b0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
374c0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
374d0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
374e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
374f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
37500 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37510 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37520 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
37530 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
37540 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
37550 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
37560 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
37570 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
37580 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
37590 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
375a0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
375b0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
375c0 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
375d0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
375e0 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
375f0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
37600 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
37610 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
37620 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
37630 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
37640 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
37650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37660 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
37670 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
37680 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
37690 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
376a0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
376b0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
376c0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
376d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
376e0 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
376f0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
37700 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
37710 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
37720 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
37730 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
37740 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
37750 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
37760 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
37770 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37780 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
37790 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75  opy of the.** [u
377a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
377b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
377c0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
377d0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
377e0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
377f0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
37800 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
37810 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
37820 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
37830 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73  * so that the [s
37840 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70  qlite3_value] sp
37850 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70  ecified in the p
37860 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61  arameter may cha
37870 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61  nge or.** be dea
37880 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73  llocated after s
37890 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
378a0 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69  lue() returns wi
378b0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
378c0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
378d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
378e0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
378f0 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
37900 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
37910 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37920 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
37930 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
37940 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
37950 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
37960 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
37970 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
37980 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
37990 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
379a0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
379b0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
379c0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
379d0 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
379e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
379f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
37a00 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
37a10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
37a20 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
37a30 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
37a40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69  ndefined..*/.voi
37a50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37a60 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
37a70 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
37a80 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
37a90 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
37aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
37ab0 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  lob64(sqlite3_co
37ac0 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69  ntext*,const voi
37ad0 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  d*,.            
37ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
37af0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f  qlite3_uint64,vo
37b00 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
37b10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37b20 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
37b30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
37b40 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
37b50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
37b60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37b70 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
37b80 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
37b90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37ba0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37bb0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
37bc0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
37bd0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
37be0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
37bf0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
37c00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37c10 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
37c20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
37c30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37c40 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
37c50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
37c60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37c70 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
37c80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
37c90 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37ca0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
37cb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
37cc0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
37cd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37ce0 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
37cf0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
37d00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37d10 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
37d20 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
37d30 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
37d40 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
37d50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37d60 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
37d70 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
37d80 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
37d90 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
37da0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
37db0 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
37dc0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
37dd0 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ing);.void sqlit
37de0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37df0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37e00 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
37e10 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
37e20 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
37e30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37e40 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
37e50 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
37e60 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
37e70 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
37e80 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37e90 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
37ea0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37eb0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
37ec0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
37ed0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
37ee0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
37ef0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
37f00 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
37f10 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
37f20 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
37f30 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20  t*, int n);.int 
37f40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
37f50 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
37f60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
37f70 74 65 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a 0a  te3_uint64 n);..
37f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37f90 20 53 65 74 74 69 6e 67 20 54 68 65 20 53 75 62   Setting The Sub
37fa0 74 79 70 65 20 4f 66 20 41 6e 20 53 51 4c 20 46  type Of An SQL F
37fb0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f  unction.** METHO
37fc0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
37fd0 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  xt.**.** The sql
37fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74  ite3_result_subt
37ff0 79 70 65 28 43 2c 54 29 20 66 75 6e 63 74 69 6f  ype(C,T) functio
38000 6e 20 63 61 75 73 65 73 20 74 68 65 20 73 75 62  n causes the sub
38010 74 79 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20 72  type of.** the r
38020 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 5b  esult from the [
38030 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
38040 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
38050 5d 20 77 69 74 68 20 0a 2a 2a 20 5b 73 71 6c 69  ] with .** [sqli
38060 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 20 74  te3_context] C t
38070 6f 20 62 65 20 74 68 65 20 76 61 6c 75 65 20 54  o be the value T
38080 2e 20 20 4f 6e 6c 79 20 74 68 65 20 6c 6f 77 65  .  Only the lowe
38090 72 20 38 20 62 69 74 73 20 0a 2a 2a 20 6f 66 20  r 8 bits .** of 
380a0 74 68 65 20 73 75 62 74 79 70 65 20 54 20 61 72  the subtype T ar
380b0 65 20 70 72 65 73 65 72 76 65 64 20 69 6e 20 63  e preserved in c
380c0 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 73 20  urrent versions 
380d0 6f 66 20 53 51 4c 69 74 65 3b 0a 2a 2a 20 68 69  of SQLite;.** hi
380e0 67 68 65 72 20 6f 72 64 65 72 20 62 69 74 73 20  gher order bits 
380f0 61 72 65 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  are discarded..*
38100 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * The number of 
38110 73 75 62 74 79 70 65 20 62 79 74 65 73 20 70 72  subtype bytes pr
38120 65 73 65 72 76 65 64 20 62 79 20 53 51 4c 69 74  eserved by SQLit
38130 65 20 6d 69 67 68 74 20 69 6e 63 72 65 61 73 65  e might increase
38140 0a 2a 2a 20 69 6e 20 66 75 74 75 72 65 20 72 65  .** in future re
38150 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
38160 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
38170 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65  3_result_subtype
38180 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38190 2a 2c 75 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b  *,unsigned int);
381a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
381b0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
381c0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
381d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
381e0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
381f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
38200 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
38210 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
38220 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
38230 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
38240 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
38250 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
38260 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
38270 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
38280 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
38290 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
382a0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
382b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
382c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
382d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
382e0 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
382f0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
38300 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
38310 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
38320 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
38330 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
38340 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
38350 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
38360 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
38370 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
38380 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
38390 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
383a0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
383b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
383c0 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
383d0 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
383e0 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
383f0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
38400 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
38410 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
38420 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
38430 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
38440 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
38450 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
38460 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
38470 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
38480 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
38490 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
384a0 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
384b0 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
384c0 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
384d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
384e0 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
384f0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
38500 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
38510 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
38520 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
38530 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
38540 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
38550 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
38560 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
38570 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
38580 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
38590 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
385a0 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
385b0 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
385c0 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
385d0 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
385e0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
385f0 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
38600 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
38610 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
38620 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
38630 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
38640 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
38650 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
38660 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
38670 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
38680 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
38690 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
386a0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
386b0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
386c0 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
386d0 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
386e0 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
386f0 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
38700 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
38710 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
38720 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
38730 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
38740 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
38750 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
38760 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
38770 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
38780 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
38790 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
387a0 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
387b0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
387c0 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
387d0 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
387e0 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
387f0 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
38800 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
38810 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
38820 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
38830 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer us