/ Hex Artifact Content
Login

Artifact 95d147c55638c7b8e9e096e27495bcef59b72668:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20  _IOERR_VNODE    
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29  _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
55f0: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5600: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5610: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5620: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5630: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5640: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5650: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5660: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
5670: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5680: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56b0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
56c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
56d0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
56f0: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5700: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5710: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5720: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5730: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5740: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5750: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5770: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
5780: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5790: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57b0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
57c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
57d0: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
57f0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5810: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5830: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5840: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5850: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5860: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5870: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
5880: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5890: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
58c0: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
58d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
58e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58f0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5900: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5910: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5920: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5930: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5940: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5950: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5960: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5970: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5980: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5990: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59a0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59c0: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
59d0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
59e0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a10: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a20: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a50: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5a60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a70: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a90: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5aa0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ab0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ad0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5ae0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5af0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b10: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b20: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5b60: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b80: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ba0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bc0: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5be0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c00: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c30: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5c60: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5c80: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5c90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ca0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5cc0: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5cd0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5ce0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5cf0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d00: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d10: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d20: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d30: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d50: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5d60: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5d70: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5d80: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5d90: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5da0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5db0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5dc0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5dd0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5de0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5df0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e10: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e20: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5e60: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5e70: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5e80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5eb0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5ec0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5ed0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5ef0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f00: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f30: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f40: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5f70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f80: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5f90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fa0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5fc0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5fd0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5fe0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ff0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6000: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6010: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6020: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6030: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
6090: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60a0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
60d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
60e0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6150: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6160: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
6190: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61a0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
61d0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
61e0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
61f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6200: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6220: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6230: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6240: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6250: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6260: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6270: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6280: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
6290: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
62c0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
62d0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
62e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6300: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6310: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6320: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6330: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50  QLITE_OPEN_FILEP
6350: 52 4f 54 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20  ROTECTION_MASK  
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6380: 78 30 30 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65  x00700000../* Re
6390: 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20  served:         
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f  0x00F00000 */../
63c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
63d0: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
63e0: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  stics.**.** The 
63f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6400: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66  istics method of
6410: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6420: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
6430: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
6440: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
6450: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73  a vector of thes
6460: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
6470: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
6480: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
6490: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
64a0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
64b0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
64c0: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
64d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
64e0: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
64f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
6500: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
6510: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
6520: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
6530: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
6540: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6550: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
6560: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
6570: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
6580: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
6590: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
65a0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
65b0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
65c0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
65d0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
65e0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
65f0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6600: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6610: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
6620: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
6630: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
6640: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
6650: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
6660: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
6670: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
6680: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
6690: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
66a0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
66b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
66c0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
66d0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
66e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
66f0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
6700: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
6710: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
6720: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53  xWrite().  The S
6730: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6740: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6750: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6760: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62  hat.** after reb
6770: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  oot following a 
6780: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c  crash or power l
6790: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79  oss, the only by
67a0: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65  tes in a.** file
67b0: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74   that were writt
67c0: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63  en at the applic
67d0: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68  ation level migh
67e0: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a  t have changed.*
67f0: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63  * and that adjac
6800: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20  ent bytes, even 
6810: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65  bytes within the
6820: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65   same sector are
6830: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74  .** guaranteed t
6840: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20  o be unchanged. 
6850: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6860: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6870: 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20  EN_OPEN.** flag 
6880: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 20  indicate that a 
6890: 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64  file cannot be d
68a0: 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e  eleted when open
68b0: 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
68c0: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
68d0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
68e0: 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73  that the file is
68f0: 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79   on.** read-only
6900: 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f   media and canno
6910: 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65  t be changed eve
6920: 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77  n by processes w
6930: 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20  ith.** elevated 
6940: 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23  privileges..*/.#
6950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6960: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6970: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6980: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6990: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
69a0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
69b0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
69c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
69d0: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
69e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
69f0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6a00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6a10: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6a20: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6a30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6a40: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6a50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6a60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6a70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
6a80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a90: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
6aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6ab0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
6ac0: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
6ad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ae0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
6af0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6b00: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
6b10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6b20: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
6b30: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
6b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b50: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
6b60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6b70: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
6b80: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6b90: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
6ba0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6bc0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6bd0: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6be0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6bf0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6c00: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6c10: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
6c20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
6c30: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
6c40: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6c50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6c60: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
6c70: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
6c80: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
6c90: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6ca0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6cb0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6cc0: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6cd0: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6ce0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
6cf0: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
6d00: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6d10: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
6d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6d30: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
6d40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6d50: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
6d60: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
6d70: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6d80: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
6d90: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6da0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6db0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6dc0: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6dd0: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6de0: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
6df0: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
6e00: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
6e10: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
6e20: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
6e30: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6e40: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6e50: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
6e60: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
6e70: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6e80: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
6e90: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
6ea0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
6eb0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
6ec0: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
6ed0: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
6ee0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
6ef0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
6f00: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
6f10: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
6f20: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
6f30: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
6f40: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
6f50: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
6f60: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
6f70: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6f80: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
6f90: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
6fa0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
6fb0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
6fc0: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
6fd0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6fe0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
6ff0: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
7000: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
7010: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
7020: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
7030: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
7040: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7050: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7060: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
7070: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
7080: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
7090: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
70a0: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
70b0: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
70c0: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
70d0: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
70e0: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
70f0: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
7100: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
7110: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
7120: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
7130: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
7140: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7150: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
7160: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
7170: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
7180: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
7190: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
71a0: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
71b0: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
71c0: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
71d0: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
71e0: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
71f0: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
7200: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
7210: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7220: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
7230: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
7240: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
7250: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7260: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7270: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
7280: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
7290: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
72a0: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
72b0: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
72c0: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
72d0: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
72e0: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
72f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7300: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
7310: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
7320: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
7330: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
7340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7350: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
7360: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
7370: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7380: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
7390: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
73a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
73b0: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
73c0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
73d0: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
73e0: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
73f0: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
7400: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
7410: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
7420: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
7430: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
7440: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
7450: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
7460: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
7470: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
7480: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
7490: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
74a0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
74b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
74c0: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
74d0: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
74e0: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
74f0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
7500: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
7510: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7520: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
7530: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
7540: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7550: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
7560: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
7570: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
7580: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
7590: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
75a0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
75b0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
75c0: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
75d0: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
75e0: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
75f0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
7600: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7610: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
7620: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7630: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
7640: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
7650: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
7660: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7670: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
7680: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
7690: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
76a0: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
76b0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
76c0: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
76d0: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
76e0: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
76f0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
7700: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
7710: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
7720: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7730: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
7740: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7750: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
7760: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
7770: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7780: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
7790: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
77a0: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
77b0: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
77c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
77d0: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
77e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
77f0: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
7800: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
7810: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
7820: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
7830: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
7840: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
7850: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
7860: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
7870: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7880: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
7890: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
78a0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
78b0: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
78c0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
78d0: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
78e0: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
78f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7900: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
7910: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
7920: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
7930: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
7940: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
7950: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
7960: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7970: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
7980: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7990: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
79a0: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
79b0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
79c0: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
79d0: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
79e0: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
79f0: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
7a00: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
7a10: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
7a20: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7a30: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
7a40: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a50: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
7a60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7a70: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
7a80: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7a90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
7aa0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7ab0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7ac0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7ad0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7ae0: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
7af0: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
7b00: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
7b10: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
7b20: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
7b30: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
7b40: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
7b50: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
7b60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7b70: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
7b80: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
7b90: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
7ba0: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
7bb0: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
7bc0: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
7bd0: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
7be0: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
7bf0: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
7c00: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
7c10: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
7c20: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
7c30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
7c40: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
7c50: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
7c60: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
7c70: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
7c80: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
7c90: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
7ca0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
7cb0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7cc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
7cd0: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
7ce0: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
7cf0: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
7d00: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
7d10: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
7d20: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
7d30: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
7d40: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
7d50: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7d60: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
7d70: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
7d80: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
7d90: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
7da0: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
7db0: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
7dc0: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
7dd0: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
7de0: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
7df0: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
7e00: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
7e10: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
7e20: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
7e30: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
7e40: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7e50: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7e60: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7e70: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7e80: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7e90: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7ea0: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
7eb0: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
7ec0: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
7ed0: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65   use..** A [file
7ee0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7ef0: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
7f00: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
7f10: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
7f20: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
7f30: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
7f40: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
7f50: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
7f60: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
7f70: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
7f80: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
7f90: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
7fa0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
7fb0: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
7fc0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
7fd0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
7fe0: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
7ff0: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
8000: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
8010: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
8020: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
8030: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
8040: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
8050: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
8060: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
8070: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
8080: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
8090: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
80a0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
80b0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
80c0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
80d0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
80e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
80f0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
8100: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
8110: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
8120: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
8130: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
8140: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8150: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8160: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
8170: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8180: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
8190: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
81a0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
81b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
81c0: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
81d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
81e0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
81f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8200: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
8210: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8220: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
8230: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8240: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
8250: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8260: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
8270: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8280: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
82b0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
82c0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
82d0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
82e0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
82f0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8300: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8310: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8320: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8330: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8340: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8350: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8360: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
8370: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
8380: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
8390: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
83a0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
83b0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
83c0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
83d0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
83e0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
83f0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8400: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8410: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8420: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8430: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8440: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8450: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8460: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
8470: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
8480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
8490: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
84a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
84b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
84c0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
84d0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
84e0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
84f0: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8500: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8510: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8520: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8530: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8540: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8550: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8560: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
8570: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
8580: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
8590: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
85a0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
85b0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
85c0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
85d0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
85e0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
85f0: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8600: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8610: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8620: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8630: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8640: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8650: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8660: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
8670: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
8680: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
8690: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
86a0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
86b0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
86c0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
86d0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
86e0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
86f0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8700: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8710: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8720: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8730: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8740: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8750: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8760: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
8770: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8780: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
8790: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
87a0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
87b0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
87c0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
87d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
87e0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
87f0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8800: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8810: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8820: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8830: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8840: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8850: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8860: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8870: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8880: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8890: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
88a0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
88b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
88c0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
88d0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
88e0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
88f0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8900: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8910: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8920: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8930: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8940: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8950: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8960: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8970: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8980: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8990: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
89a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
89b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
89c0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
89d0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
89e0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
89f0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8a00: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8a10: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8a20: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8a30: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8a40: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8a50: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8a60: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8a70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8a80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8a90: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8aa0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8ab0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8ac0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8ad0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8ae0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8af0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8b00: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8b10: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8b20: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8b30: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
8b40: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
8b50: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
8b60: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8b70: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
8b80: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8b90: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8ba0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8bb0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8bc0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8bd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8be0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8bf0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8c00: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8c10: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8c20: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8c30: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
8c40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8c50: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8c60: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8c70: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8c80: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8c90: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8ca0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8cb0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8cc0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8cd0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8ce0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8cf0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8d00: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8d10: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8d20: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8d30: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8d40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8d50: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8d60: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8d70: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8d80: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8d90: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8da0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8db0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
8dc0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
8dd0: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
8de0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
8df0: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
8e00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8e10: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8e20: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
8e30: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8e40: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
8e50: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
8e60: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
8e70: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
8e80: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
8e90: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
8ea0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
8eb0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
8ec0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
8ed0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
8ee0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8ef0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
8f00: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
8f10: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
8f20: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
8f30: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
8f40: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
8f50: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
8f60: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
8f70: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
8f80: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
8f90: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
8fa0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
8fb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8fc0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
8fd0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8fe0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8ff0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9000: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9010: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9020: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9030: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9040: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9050: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9060: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
9070: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
9080: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
9090: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
90a0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
90b0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
90c0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
90d0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
90e0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
90f0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9100: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9110: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9120: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9130: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9140: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9150: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9160: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
9170: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
9180: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
9190: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
91a0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
91b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91c0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
91d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
91e0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
91f0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9200: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9210: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9220: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9230: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9240: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9250: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9260: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9280: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
9290: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
92a0: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
92b0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
92c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
92d0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
92e0: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
92f0: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9300: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9310: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9320: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9330: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9340: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9350: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
9360: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
9370: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
9380: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
9390: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
93a0: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
93b0: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
93c0: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
93d0: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
93e0: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
93f0: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9400: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9410: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9420: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9430: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9440: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9450: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
9460: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
9470: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
9480: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
9490: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
94a0: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
94b0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
94c0: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
94d0: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
94e0: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
94f0: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9500: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9510: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9520: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9530: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9540: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9550: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9560: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
9570: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
9580: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
9590: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
95a0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
95b0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
95c0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
95d0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
95e0: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
95f0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9600: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9610: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9620: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9630: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9640: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9650: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9660: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
9670: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
9680: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
9690: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
96a0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
96b0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
96c0: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
96d0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
96e0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
96f0: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9700: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9710: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9720: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9730: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9740: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9750: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
9760: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
9770: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
9780: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
9790: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
97a0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
97b0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
97c0: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
97d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
97e0: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
97f0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9800: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9810: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
9820: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9830: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9840: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9850: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9860: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9870: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
9880: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
9890: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
98a0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
98b0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
98c0: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
98d0: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
98e0: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
98f0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
9900: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
9910: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
9920: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9930: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9940: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
9950: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
9960: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
9970: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
9980: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
9990: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
99a0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
99b0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
99c0: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
99d0: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
99e0: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
99f0: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
9a00: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
9a10: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
9a20: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
9a30: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
9a40: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
9a50: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
9a60: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
9a70: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
9a80: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
9a90: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
9aa0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
9ab0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
9ac0: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
9ad0: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
9ae0: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
9af0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9b00: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
9b10: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
9b20: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
9b30: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
9b40: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
9b50: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
9b60: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
9b70: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
9b80: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
9b90: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
9ba0: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
9bb0: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
9bc0: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
9bd0: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
9be0: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
9bf0: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
9c00: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
9c10: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
9c20: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
9c30: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
9c40: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
9c50: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
9c60: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
9c70: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
9c80: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
9c90: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
9ca0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9cb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9cc0: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
9cd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9ce0: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
9cf0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
9d00: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
9d10: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
9d20: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
9d30: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
9d40: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
9d50: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
9d60: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
9d70: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9d80: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
9d90: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
9da0: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
9db0: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
9dc0: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
9dd0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
9de0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
9df0: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
9e00: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9e10: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
9e20: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
9e30: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
9e40: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
9e50: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
9e60: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
9e70: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
9e80: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
9e90: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
9ea0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
9eb0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
9ec0: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
9ed0: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
9ee0: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
9ef0: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
9f00: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
9f10: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
9f20: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
9f30: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
9f40: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
9f50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9f60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9f70: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9f80: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9f90: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9fa0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9fb0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9fc0: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
9fd0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9fe0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9ff0: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
a000: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
a010: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a020: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a030: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a040: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
a050: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
a060: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a070: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a080: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a090: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a0a0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a0b0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
a0c0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a0d0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a0e0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
a0f0: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
a100: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
a110: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
a120: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
a130: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
a140: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
a150: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
a160: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
a170: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a180: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
a190: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a1a0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a1b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a1c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a1d0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a1e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a1f0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a200: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a210: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
a220: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a230: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
a240: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
a250: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a260: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a270: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a280: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
a290: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
a2a0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a2b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a2c0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
a2d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
a2e0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a2f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
a300: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
a310: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
a320: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
a330: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
a340: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
a350: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
a360: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
a370: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
a380: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
a390: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
a3a0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
a3b0: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
a3c0: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
a3d0: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
a3e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a3f0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
a400: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a410: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
a420: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
a430: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
a440: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
a450: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
a460: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
a470: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
a480: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
a490: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
a4a0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
a4b0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
a4c0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
a4d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
a4e0: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
a4f0: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
a500: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
a510: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
a520: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a530: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
a540: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
a550: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
a560: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
a570: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
a580: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
a590: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
a5a0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
a5b0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
a5c0: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
a5d0: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
a5e0: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
a5f0: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
a600: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
a610: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
a620: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
a630: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
a640: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
a650: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
a660: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
a670: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
a680: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
a690: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
a6a0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
a6b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a6c0: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
a6d0: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
a6e0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
a6f0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
a700: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a710: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a720: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
a730: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
a740: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
a750: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
a760: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a770: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
a780: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
a790: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
a7a0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
a7b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a7c0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a7d0: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
a7e0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
a7f0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
a800: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
a810: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
a820: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
a830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
a840: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
a850: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
a860: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
a870: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
a880: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
a890: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
a8a0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
a8b0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
a8c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a8d0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a8e0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
a8f0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
a900: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
a910: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
a920: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
a930: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
a940: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
a950: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
a960: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
a970: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
a980: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
a990: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
a9a0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
a9b0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
a9c0: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
a9d0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
a9e0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a9f0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
aa00: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
aa10: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
aa20: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
aa30: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
aa40: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
aa50: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aa60: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
aa70: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
aa80: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
aa90: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
aaa0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
aab0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
aac0: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
aad0: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
aae0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
aaf0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
ab00: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
ab10: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
ab20: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
ab30: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
ab40: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
ab50: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
ab60: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
ab70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ab80: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ab90: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
aba0: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
abb0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
abc0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
abd0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
abe0: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
abf0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
ac00: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
ac10: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
ac20: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
ac30: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
ac40: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
ac50: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
ac60: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
ac70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
ac80: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
ac90: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
aca0: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
acb0: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
acc0: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
acd0: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
ace0: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
acf0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
ad00: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
ad10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
ad20: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
ad30: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ad40: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
ad50: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
ad60: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
ad70: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
ad80: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
ad90: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
ada0: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
adb0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
adc0: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
add0: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
ade0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
adf0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
ae00: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
ae10: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
ae20: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
ae30: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
ae40: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
ae50: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
ae60: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
ae70: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
ae80: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
ae90: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
aea0: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
aeb0: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
aec0: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
aed0: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
aee0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
aef0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
af00: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
af10: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
af20: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
af30: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
af40: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
af50: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
af60: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
af70: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
af80: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
af90: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
afa0: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
afb0: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
afc0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
afd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
afe0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
aff0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
b000: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
b010: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b020: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
b030: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
b040: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
b050: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b060: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
b070: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
b080: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
b090: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
b0a0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b0b0: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
b0c0: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
b0d0: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
b0e0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b0f0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
b100: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
b110: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
b120: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
b130: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
b140: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b150: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
b160: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
b170: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
b180: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
b190: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
b1a0: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
b1b0: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
b1c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
b1d0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
b1e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b1f0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
b200: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
b210: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
b220: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
b230: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
b240: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b250: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b260: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b270: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b280: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b290: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b2a0: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b2b0: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b2c0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b2d0: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b2e0: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b2f0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b300: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b310: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b320: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b330: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b340: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b350: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b360: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b370: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b380: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b390: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b3a0: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b3b0: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b3c0: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b3d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b3e0: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b3f0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b400: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b410: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b420: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b430: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b440: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b450: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b460: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b470: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b480: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b490: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b4a0: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b4b0: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b4c0: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b4d0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b4e0: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b4f0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b500: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b510: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b520: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b530: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b540: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b550: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b560: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b570: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b580: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b590: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b5a0: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
b5b0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
b5c0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
b5d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b5e0: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
b5f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b600: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
b610: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
b620: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
b630: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
b640: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
b650: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
b660: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
b670: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
b680: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
b690: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
b6a0: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
b6b0: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
b6c0: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
b6d0: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
b6e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b6f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b700: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
b710: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b720: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b730: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
b740: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
b750: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
b760: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
b770: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
b780: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
b790: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
b7a0: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
b7b0: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
b7c0: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
b7d0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
b7e0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
b7f0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
b800: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
b810: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
b820: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
b830: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
b850: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
b860: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
b870: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
b880: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
b890: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
b8a0: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
b8b0: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
b8c0: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
b8d0: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
b8e0: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
b8f0: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
b900: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
b910: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
b920: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
b930: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
b940: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
b950: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
b960: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
b970: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
b980: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
b990: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
b9a0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
b9b0: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
b9c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
b9d0: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
b9e0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
b9f0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
ba00: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
ba10: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
ba20: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
ba30: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
ba40: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
ba50: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
ba60: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ba70: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
ba80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
ba90: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
baa0: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
bab0: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
bac0: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
bad0: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
bae0: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
baf0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
bb00: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
bb10: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
bb20: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
bb30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bb40: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
bb50: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
bb60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bb70: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
bb80: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
bb90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
bba0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
bbb0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
bbc0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bbd0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
bbe0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
bbf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
bc00: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
bc10: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
bc20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
bc30: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
bc40: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
bc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
bc60: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
bc70: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
bc80: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
bc90: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
bca0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
bcb0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
bcc0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
bcd0: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
bce0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
bcf0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
bd00: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
bd10: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
bd20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
bd30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bd40: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
bd50: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
bd60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bd70: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
bd80: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
bd90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bda0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
bdb0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
bdc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bdd0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
bde0: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
bdf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
be00: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
be10: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
be20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
be30: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
be40: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
be50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
be60: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
be70: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
be80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
be90: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
bea0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
beb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
bec0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
bed0: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
bee0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
bef0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
bf00: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
bf10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
bf20: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
bf30: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
bf40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
bf50: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
bf60: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
bf70: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
bf80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bf90: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
bfa0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
bfb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bfc0: 32 36 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65  26../* deprecate
bfd0: 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69  d names */.#defi
bfe0: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
bff0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c000: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
c010: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
c030: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c040: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c050: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
c060: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
c070: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
c080: 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54             SQLIT
c090: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
c0a0: 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  NO.../*.** CAPI3
c0b0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
c0c0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
c0d0: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
c0e0: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
c0f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
c100: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
c110: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
c120: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
c130: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
c140: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
c150: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
c160: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
c170: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
c180: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
c190: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
c1a0: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
c1b0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
c1c0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
c1d0: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
c1e0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
c1f0: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
c200: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c210: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
c220: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
c230: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
c240: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
c250: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
c260: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
c270: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
c280: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c290: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
c2a0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
c2b0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
c2c0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
c2d0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
c2e0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
c2f0: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
c300: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
c310: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
c320: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
c330: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
c340: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
c350: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
c360: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
c370: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c380: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
c390: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
c3a0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
c3b0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
c3c0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
c3d0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
c3e0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
c3f0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
c400: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
c410: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
c420: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
c430: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
c440: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
c450: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
c460: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
c470: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
c480: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
c490: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
c4a0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
c4b0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
c4c0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
c4d0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
c4e0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
c4f0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
c500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
c510: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
c520: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
c530: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
c540: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
c550: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
c560: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
c570: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
c580: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c590: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
c5a0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
c5b0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
c5c0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
c5d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
c5e0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
c5f0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
c600: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
c610: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
c620: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
c630: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
c640: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
c650: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
c660: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
c670: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
c680: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
c690: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
c6a0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
c6b0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
c6c0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
c6d0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
c6e0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
c6f0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
c700: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
c710: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
c720: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
c730: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
c740: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
c750: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
c760: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
c770: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
c780: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
c790: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
c7a0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
c7b0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
c7c0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
c7d0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
c7e0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
c7f0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
c800: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
c810: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
c820: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
c830: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
c840: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
c850: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
c860: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
c870: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
c880: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
c890: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
c8a0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
c8b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c8c0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
c8d0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
c8e0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
c8f0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
c900: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
c910: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
c920: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
c930: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
c940: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
c950: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c960: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
c970: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
c980: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
c990: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
c9a0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
c9b0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
c9c0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
c9d0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
c9e0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
c9f0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
ca00: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
ca10: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
ca20: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
ca30: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
ca40: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
ca50: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
ca60: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
ca70: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
ca80: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
ca90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
caa0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
cab0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
cac0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
cad0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
cae0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
caf0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
cb00: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
cb10: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
cb20: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
cb30: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
cb40: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
cb50: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
cb60: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
cb70: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
cb80: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
cb90: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
cba0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
cbb0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
cbc0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
cbd0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
cbe0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
cbf0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
cc00: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
cc10: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
cc20: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
cc30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
cc40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
cc50: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
cc60: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
cc70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
cc80: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
cc90: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
cca0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
ccb0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
ccc0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
ccd0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
cce0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
ccf0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
cd00: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
cd10: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
cd20: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
cd30: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
cd40: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
cd50: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
cd60: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
cd70: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
cd80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
cd90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
cda0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
cdb0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
cdc0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
cdd0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
cde0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
cdf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
ce00: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ce10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
ce20: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ce30: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ce40: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
ce50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
ce60: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
ce70: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ce80: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
ce90: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cea0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
ceb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cec0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
ced0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
cee0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
cef0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
cf00: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
cf10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
cf20: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
cf30: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
cf40: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
cf50: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
cf60: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
cf70: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
cf80: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
cf90: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
cfa0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
cfb0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
cfc0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
cfd0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
cfe0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
cff0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
d000: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
d010: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
d020: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
d030: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
d040: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
d050: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
d060: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
d070: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
d080: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
d090: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
d0a0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
d0b0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
d0c0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
d0d0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
d0e0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
d0f0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
d100: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
d110: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
d120: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
d130: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
d140: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
d150: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
d160: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d170: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d180: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
d190: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d1a0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
d1b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
d1c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d1d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
d1e0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
d1f0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
d200: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
d210: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
d220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d230: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
d240: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
d250: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
d260: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
d270: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
d280: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
d290: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
d2a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d2b0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
d2c0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
d2d0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
d2e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
d2f0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
d300: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
d310: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
d320: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
d330: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
d340: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
d350: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
d360: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
d370: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
d380: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
d390: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
d3a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
d3b0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
d3c0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
d3d0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
d3e0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
d3f0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
d400: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
d410: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
d420: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
d430: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
d440: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
d450: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
d460: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
d470: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
d480: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
d490: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
d4a0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
d4b0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
d4c0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
d4d0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
d4e0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
d4f0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
d500: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
d510: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
d520: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
d530: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
d540: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
d550: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
d560: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
d570: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
d580: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
d590: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
d5a0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
d5b0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
d5c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
d5d0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
d5e0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
d5f0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
d600: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
d610: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
d620: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
d630: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
d640: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
d650: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
d660: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
d670: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
d680: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
d690: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
d6a0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
d6b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
d6c0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
d6d0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
d6e0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
d6f0: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
d700: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
d710: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
d720: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
d730: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
d740: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
d750: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
d760: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
d770: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
d780: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
d790: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
d7a0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
d7b0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
d7c0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
d7d0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
d7e0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
d7f0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
d800: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
d810: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
d820: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
d830: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
d840: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
d850: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
d860: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
d870: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
d880: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
d890: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
d8a0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
d8b0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
d8c0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
d8d0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
d8e0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
d8f0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
d900: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
d910: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
d920: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
d930: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
d940: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
d950: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
d960: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
d970: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
d980: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
d990: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
d9a0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
d9b0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
d9c0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
d9d0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
d9e0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
d9f0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
da00: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
da10: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
da20: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
da30: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
da40: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
da50: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
da60: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
da70: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
da80: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
da90: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
daa0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
dab0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
dac0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
dad0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
dae0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
daf0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
db00: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
db10: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
db20: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
db30: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
db40: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
db50: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
db60: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
db70: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
db80: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
db90: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
dba0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
dbb0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
dbc0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
dbd0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
dbe0: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
dbf0: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
dc00: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
dc10: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
dc20: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
dc30: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
dc40: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
dc50: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
dc60: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
dc70: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
dc80: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
dc90: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
dca0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
dcb0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
dcc0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
dcd0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
dce0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
dcf0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
dd00: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
dd10: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
dd20: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
dd30: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
dd40: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
dd50: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
dd60: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
dd70: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
dd80: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dd90: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
dda0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
ddb0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
ddc0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
ddd0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
dde0: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
ddf0: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
de00: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
de10: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
de20: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
de30: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
de40: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
de50: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
de60: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
de70: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
de80: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
de90: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
dea0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
deb0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
dec0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
ded0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
dee0: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
def0: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
df00: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
df10: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
df20: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
df30: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
df40: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
df50: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
df60: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
df70: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
df80: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
df90: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
dfa0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
dfb0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
dfc0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
dfd0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
dfe0: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
dff0: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
e000: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
e010: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
e020: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
e030: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
e040: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
e050: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
e060: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e070: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
e080: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
e090: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
e0a0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
e0b0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
e0c0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
e0d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
e0e0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
e0f0: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
e100: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
e110: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
e120: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
e130: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
e140: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
e150: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
e160: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
e170: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
e180: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
e190: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
e1a0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
e1b0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
e1c0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
e1d0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
e1e0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
e1f0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
e200: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
e210: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
e220: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
e230: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
e240: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
e250: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
e260: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
e270: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
e280: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
e290: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
e2a0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
e2b0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
e2c0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
e2d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e2e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
e2f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
e300: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
e310: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
e320: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
e330: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
e340: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e350: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
e360: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
e370: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
e380: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e390: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
e3a0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
e3b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
e3c0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
e3d0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e3e0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
e3f0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
e400: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
e410: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
e420: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e430: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
e440: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
e450: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
e460: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
e470: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
e480: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
e490: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
e4a0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
e4b0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
e4c0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
e4d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
e4e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
e4f0: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
e500: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
e510: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e520: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
e530: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e540: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
e550: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
e560: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
e570: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
e580: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
e590: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
e5a0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
e5b0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
e5c0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
e5d0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
e5e0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e5f0: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
e600: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
e610: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
e620: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
e630: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
e640: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
e650: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
e660: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
e670: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
e680: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
e690: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
e6a0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
e6b0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e6c0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
e6d0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
e6e0: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
e6f0: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
e700: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
e710: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e720: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e730: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
e740: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
e750: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
e760: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
e770: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e780: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e790: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
e7a0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
e7b0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e7c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e7d0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
e7e0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
e7f0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
e800: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
e810: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
e820: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
e830: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
e840: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
e850: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
e860: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
e870: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
e880: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
e890: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
e8a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
e8b0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
e8c0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
e8d0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
e8e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
e8f0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
e900: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
e910: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
e920: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e930: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
e940: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
e950: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
e960: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
e970: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
e980: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
e990: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
e9a0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
e9b0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
e9c0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e9d0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
e9e0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
e9f0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
ea00: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ea10: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
ea20: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ea30: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
ea40: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
ea50: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
ea60: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
ea70: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
ea80: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
ea90: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
eaa0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
eab0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
eac0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
ead0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
eae0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
eaf0: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
eb00: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
eb10: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
eb20: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
eb30: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
eb40: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
eb50: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
eb60: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
eb70: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
eb80: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
eb90: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
eba0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
ebb0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
ebc0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
ebd0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
ebe0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
ebf0: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
ec00: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
ec10: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
ec20: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
ec30: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
ec40: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
ec50: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
ec60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
ec70: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
ec80: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
ec90: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
eca0: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
ecb0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
ecc0: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
ecd0: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
ece0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ecf0: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
ed00: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
ed10: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
ed20: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
ed30: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
ed40: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
ed50: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
ed60: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
ed70: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
ed80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
ed90: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
eda0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
edb0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
edc0: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
edd0: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
ede0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
edf0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ee00: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
ee10: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
ee20: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
ee30: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ee40: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
ee50: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
ee60: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
ee70: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
ee80: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
ee90: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
eea0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
eeb0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
eec0: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
eed0: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
eee0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
eef0: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
ef00: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f  s.** was given o
ef10: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
ef20: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
ef30: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
ef40: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
ef50: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
ef60: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
ef70: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
ef80: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
ef90: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
efa0: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
efb0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
efc0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
efd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
efe0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
eff0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
f000: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
f010: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
f020: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
f030: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
f040: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f050: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
f060: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
f070: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
f080: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
f090: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
f0a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
f0b0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
f0c0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
f0d0: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
f0e0: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
f0f0: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
f100: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
f110: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
f120: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
f130: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
f140: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
f150: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
f160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f170: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
f180: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f190: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
f1a0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
f1b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
f1c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
f1d0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
f1e0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
f1f0: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
f200: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f210: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
f220: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
f230: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
f240: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
f250: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f260: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
f270: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
f280: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
f290: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
f2a0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
f2b0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
f2c0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
f2d0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
f2e0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
f2f0: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
f300: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
f310: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
f320: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
f330: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
f340: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f350: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
f360: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
f370: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
f380: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
f390: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
f3a0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
f3b0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
f3c0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
f3d0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
f3e0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
f3f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
f400: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
f410: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
f420: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f430: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
f440: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
f450: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f460: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
f470: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
f480: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
f490: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
f4a0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
f4b0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f4c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
f4d0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
f4e0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
f4f0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
f500: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f510: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
f520: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
f530: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
f540: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
f550: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
f560: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
f570: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
f580: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
f590: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
f5a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f5b0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
f5c0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
f5d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f5e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
f5f0: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
f600: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
f610: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
f620: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
f630: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f640: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
f650: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
f660: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
f670: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
f680: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f690: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
f6a0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
f6b0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
f6c0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
f6d0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
f6e0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
f6f0: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
f700: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
f710: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
f720: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
f730: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
f740: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
f750: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
f760: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
f770: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
f780: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
f790: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
f7a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
f7b0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
f7c0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
f7d0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
f7e0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
f7f0: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
f800: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
f810: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
f820: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
f830: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
f840: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
f850: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
f860: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
f870: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
f880: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
f890: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
f8a0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
f8b0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
f8c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f8d0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
f8e0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
f8f0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
f900: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
f910: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
f920: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
f930: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
f940: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
f950: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
f960: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
f970: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
f980: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
f990: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f9a0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
f9b0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
f9c0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
f9d0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
f9e0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
f9f0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
fa00: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
fa10: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
fa20: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
fa30: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
fa40: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
fa50: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
fa60: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
fa70: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
fa80: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
fa90: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
faa0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fab0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
fac0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
fad0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
fae0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
faf0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
fb00: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
fb10: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
fb20: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
fb30: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
fb40: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
fb50: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
fb60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
fb70: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
fb80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fb90: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
fba0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
fbb0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fbc0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
fbd0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
fbe0: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
fbf0: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
fc00: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
fc10: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
fc20: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
fc30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
fc40: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
fc50: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
fc60: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
fc70: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
fc80: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
fc90: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
fca0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
fcb0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
fcc0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
fcd0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
fce0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
fcf0: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
fd00: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
fd10: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
fd20: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
fd30: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
fd40: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fd50: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
fd60: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
fd70: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
fd80: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
fd90: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
fda0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
fdb0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
fdc0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
fdd0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
fde0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
fdf0: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
fe00: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
fe10: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
fe20: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
fe30: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
fe40: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
fe50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
fe60: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
fe70: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
fe80: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
fe90: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
fea0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
feb0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
fec0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
fed0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
fee0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fef0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
ff00: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
ff10: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ff20: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
ff30: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
ff40: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
ff50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
ff60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
ff70: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
ff80: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
ff90: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
ffa0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
ffb0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
ffc0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
ffd0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ffe0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
fff0: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
10000 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
10010 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
10020 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
10030 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
10040 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
10050 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
10060 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
10070 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
10080 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
10090 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
100a0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
100b0 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
100c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
100d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
100e0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
100f0 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
10100 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
10110 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
10120 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
10130 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
10140 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10150 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
10160 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
10170 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
10180 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
10190 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
101a0 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
101b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
101c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
101d0 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
101e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
101f0 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
10200 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
10210 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
10220 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
10230 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
10240 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
10250 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10260 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10270 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
10280 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
10290 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
102a0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
102b0 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
102c0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
102d0 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
102e0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
102f0 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
10300 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
10310 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
10320 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
10330 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
10340 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
10350 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
10360 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
10370 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
10380 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
10390 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
103a0 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69  *.** <b>The sqli
103b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
103c0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
103d0 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70  readsafe. The ap
103e0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
103f0 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t ensure that no
10400 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
10410 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
10420 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
10430 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
10440 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10450 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a  is running.</b>.
10460 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10470 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10480 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  face.** may only
10490 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
104a0 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
104b0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
104c0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
104d0 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
104e0 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
104f0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10500 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
10510 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10520 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
10530 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10540 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
10550 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10560 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
10570 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
10580 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
10590 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
105a0 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
105b0 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
105c0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
105d0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
105e0 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
105f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
10600 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10610 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
10620 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10630 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10640 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
10650 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10660 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10670 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
10680 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
10690 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
106a0 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
106b0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
106c0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
106d0 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
106e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
106f0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10700 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
10710 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10720 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10730 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10740 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
10750 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
10760 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10770 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
10780 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
10790 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
107a0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
107b0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
107c0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
107d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
107e0 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
107f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10800 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
10810 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10820 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
10830 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
10840 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10850 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10860 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
10870 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
10880 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
10890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
108a0 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
108b0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
108c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
108d0 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
108e0 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
108f0 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
10900 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
10910 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
10920 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
10930 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
10940 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
10950 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
10960 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
10970 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
10980 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
10990 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
109a0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
109b0 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
109c0 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
109d0 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
109e0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
109f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
10a00 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
10a10 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
10a20 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
10a30 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10a40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
10a50 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
10a60 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
10a70 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
10a80 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
10a90 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
10aa0 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
10ab0 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
10ac0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
10ad0 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
10ae0 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
10af0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10b00 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
10b10 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
10b20 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
10b30 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
10b40 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
10b50 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
10b60 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
10b70 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
10b80 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
10b90 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
10ba0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
10bb0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
10bc0 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
10bd0 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
10be0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
10bf0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
10c00 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
10c10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10c20 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
10c30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10c40 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
10c50 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10c60 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
10c70 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
10c80 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
10c90 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
10ca0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
10cb0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
10cc0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
10cd0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
10ce0 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
10cf0 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
10d00 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
10d10 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
10d20 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
10d30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10d40 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
10d50 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
10d60 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
10d70 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
10d80 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
10d90 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
10da0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
10db0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
10dc0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
10dd0 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
10de0 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
10df0 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
10e00 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
10e10 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
10e20 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
10e30 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
10e40 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
10e50 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
10e60 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
10e70 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
10e80 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
10e90 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
10ea0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
10eb0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
10ec0 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
10ed0 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
10ee0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
10ef0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
10f00 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
10f10 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
10f20 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
10f30 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
10f40 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
10f50 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
10f60 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
10f70 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
10f80 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
10f90 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
10fa0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
10fb0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
10fc0 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
10fd0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
10fe0 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
10ff0 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
11000 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
11010 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
11020 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
11030 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11040 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
11050 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
11060 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
11070 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
11080 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
11090 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
110a0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
110b0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
110c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
110d0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
110e0 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
110f0 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
11100 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
11110 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
11120 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
11130 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
11140 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
11150 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
11160 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
11170 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
11180 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
11190 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
111a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
111b0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
111c0 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
111d0 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
111e0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
111f0 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
11200 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
11210 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
11220 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
11230 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
11240 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
11250 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
11260 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
11270 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
11280 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11290 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
112a0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
112b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
112c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
112d0 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
112e0 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
112f0 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
11300 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
11310 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
11320 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
11330 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
11340 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
11350 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
11360 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
11370 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
11380 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
11390 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
113a0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
113b0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
113c0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
113d0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
113e0 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
113f0 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
11400 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
11410 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11420 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
11430 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
11440 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
11450 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
11460 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
11470 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
11480 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
11490 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
114a0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
114b0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
114c0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
114d0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
114e0 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
114f0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
11500 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
11510 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
11520 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
11530 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
11540 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
11550 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
11560 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
11570 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
11580 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
11590 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
115a0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
115b0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
115c0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
115d0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
115e0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
115f0 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
11600 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
11610 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11620 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
11630 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
11640 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
11650 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
11660 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
11670 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
11680 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
11690 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
116a0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
116b0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
116c0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
116d0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
116e0 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
116f0 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
11700 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
11710 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
11720 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
11730 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
11740 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
11750 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
11760 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
11770 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
11780 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
11790 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
117a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
117b0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
117c0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
117d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
117e0 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
117f0 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
11800 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
11810 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
11820 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
11830 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
11840 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11850 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
11860 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11870 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
11880 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
11890 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
118a0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
118b0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
118c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
118d0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
118e0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
118f0 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
11900 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
11910 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
11920 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
11930 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
11940 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
11950 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11960 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
11970 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11980 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11990 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
119a0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
119b0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
119c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
119d0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
119e0 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
119f0 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
11a00 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
11a10 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
11a20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11a30 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
11a40 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
11a50 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
11a60 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
11a70 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
11a80 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
11a90 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
11aa0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11ab0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
11ac0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
11ad0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
11ae0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
11af0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11b00 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
11b10 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11b20 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
11b30 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
11b40 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
11b50 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
11b60 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11b70 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
11b80 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
11b90 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
11ba0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
11bb0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
11bc0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
11bd0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
11be0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
11bf0 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
11c00 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11c10 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
11c20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
11c30 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
11c40 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
11c50 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
11c60 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11c70 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
11c80 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
11c90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11ca0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
11cb0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
11cc0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
11cd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11ce0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11cf0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11d00 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11d10 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11d20 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
11d30 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
11d40 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
11d50 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
11d60 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
11d70 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
11d80 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
11d90 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
11da0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
11db0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
11dc0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11dd0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11de0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11df0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11e00 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11e10 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11e20 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11e30 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
11e40 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
11e50 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
11e60 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
11e70 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
11e80 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
11e90 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11ea0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
11eb0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11ec0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
11ed0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
11ee0 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
11ef0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11f00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11f10 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
11f20 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
11f30 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
11f40 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
11f50 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
11f60 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
11f70 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
11f80 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
11f90 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
11fa0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
11fb0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
11fc0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
11fd0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
11fe0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11ff0 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12000 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12010 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
12020 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
12030 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
12040 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
12050 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
12060 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
12070 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12080 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
12090 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
120a0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
120b0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
120c0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
120d0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
120e0 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
120f0 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
12100 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
12110 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
12120 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
12130 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
12140 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
12150 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12160 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12170 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12180 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12190 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
121a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
121b0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
121c0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
121d0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
121e0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
121f0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12200 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12210 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12220 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12230 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12240 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12250 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
12260 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
12270 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12280 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
12290 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
122a0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
122b0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
122c0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
122d0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
122e0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
122f0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12300 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12310 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
12320 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12330 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
12340 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
12350 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
12360 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
12370 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
12380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12390 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
123a0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
123b0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
123c0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
123d0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
123e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
123f0 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
12400 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
12410 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
12420 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
12430 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
12440 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
12450 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
12460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12470 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
12480 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
12490 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
124a0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
124b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
124c0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
124d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
124e0 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
124f0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
12500 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
12510 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12520 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12530 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12540 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12550 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12560 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12570 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12580 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
12590 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
125a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
125b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
125c0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
125d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
125e0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
125f0 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
12600 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12610 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
12620 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12630 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12640 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
12650 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12660 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
12670 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
12680 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
12690 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
126a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
126b0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
126c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
126d0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
126e0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
126f0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
12700 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
12710 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
12720 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
12730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12740 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12750 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
12760 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
12770 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12780 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
12790 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
127a0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
127b0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
127c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
127d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
127e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
127f0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
12800 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12810 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
12820 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12830 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12840 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
12850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12860 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
12870 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
12880 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12890 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
128a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
128b0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
128c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
128d0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
128e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
128f0 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
12900 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
12910 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12920 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12930 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12940 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
12950 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12960 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
12970 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
12980 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
12990 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
129a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
129b0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
129c0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
129d0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
129e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
129f0 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
12a00 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
12a10 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
12a20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12a30 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12a40 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
12a50 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12a70 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12a80 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
12a90 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
12aa0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
12ab0 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
12ac0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
12ad0 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
12ae0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
12af0 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
12b00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12b10 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
12b20 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
12b30 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12b40 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
12b50 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
12b60 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
12b70 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12b80 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12b90 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12ba0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12bb0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12bc0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12bd0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12be0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12bf0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12c00 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12c10 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12c20 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
12c30 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
12c40 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12c50 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
12c60 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
12c70 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12c80 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12c90 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12ca0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12cb0 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12cc0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12cd0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12ce0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12cf0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
12d00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12d10 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
12d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12d30 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
12d40 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
12d50 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
12d60 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12d70 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12d80 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12d90 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
12da0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
12db0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
12dc0 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
12dd0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12de0 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
12df0 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
12e00 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
12e10 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
12e20 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
12e30 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
12e40 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
12e50 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
12e60 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
12e70 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
12e80 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
12e90 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
12ea0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
12eb0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12ec0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12ed0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
12ee0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
12ef0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
12f00 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12f10 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
12f20 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
12f30 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
12f40 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
12f50 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
12f60 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
12f70 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
12f80 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
12f90 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
12fa0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
12fb0 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
12fc0 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
12fd0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
12fe0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
12ff0 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
13000 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
13010 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
13020 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
13030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
13040 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
13050 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
13060 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
13070 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
13080 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
13090 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
130a0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
130b0 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
130c0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
130d0 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
130e0 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
130f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
13100 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
13110 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
13120 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
13130 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
13140 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13150 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
13160 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
13170 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
13180 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
13190 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
131a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
131b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
131c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
131d0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
131e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
131f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13200 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
13210 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13220 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13230 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13240 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
13250 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
13260 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
13270 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
13280 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13290 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
132a0 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
132b0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
132c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
132d0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
132e0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
132f0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
13300 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
13310 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a  CONFIG_PCACHE2].
13320 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13330 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65   option..** ^The
13340 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13350 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
13360 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13370 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
13380 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
13390 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
133a0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
133b0 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
133c0 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
133d0 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
133e0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
133f0 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
13400 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
13410 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
13420 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
13430 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
13440 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
13450 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
13460 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
13470 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
13480 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
13490 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
134a0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
134b0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
134c0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ned using the [S
134d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
134e0 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f  CHE_HDRSZ] optio
134f0 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  n .** to [sqlite
13500 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20  3_config()]..** 
13510 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13520 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13530 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13540 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
13550 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
13560 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
13570 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
13580 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
13590 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  d pointer to an 
135a0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
135b0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74  lock of memory t
135c0 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61  hat.** is at lea
135d0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
135e0 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69   memory, otherwi
135f0 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  se subsequent be
13600 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
13610 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69  efined..** ^SQLi
13620 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
13630 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
13640 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
13650 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
13660 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
13670 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
13680 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
13690 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
136a0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
136b0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
136c0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
136d0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
136e0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
136f0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
13700 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13710 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13720 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
13730 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
13740 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
13750 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13760 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
13770 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
13780 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
137a0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
137b0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
137c0 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
137d0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
137e0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
137f0 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13800 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13810 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
13820 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
13830 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
13840 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
13850 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
13860 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
13870 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13880 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
13890 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
138a0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
138b0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
138c0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
138d0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
138e0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
138f0 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
13900 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
13910 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
13920 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
13930 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13940 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13960 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
13970 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
13980 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
13990 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
139a0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
139b0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
139c0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
139d0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
139e0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
139f0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13a00 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13a10 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
13a20 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
13a30 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
13a40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13a50 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
13a60 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
13a70 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13a80 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13a90 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13aa0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
13ab0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
13ac0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
13ad0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
13ae0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13af0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13b00 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13b10 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
13b20 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
13b30 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
13b40 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
13b50 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
13b60 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
13b70 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13b80 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
13b90 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
13ba0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
13bb0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13bc0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13bd0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13be0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13bf0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13c00 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13c10 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13c20 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
13c30 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
13c40 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
13c50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13c60 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13c70 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
13c80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13c90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13ca0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13cb0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13cc0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
13cd0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
13ce0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13cf0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13d00 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13d10 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13d20 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
13d30 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13d40 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
13d50 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
13d60 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
13d70 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
13d80 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13d90 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13da0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
13db0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
13dc0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13dd0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13de0 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
13df0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13e00 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
13e10 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
13e20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13e30 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13e40 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13e50 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13e60 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13e70 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13e80 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13e90 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13ea0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13eb0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13ec0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13ed0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13ee0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13ef0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
13f00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13f10 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
13f20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
13f30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13f40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
13f50 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
13f60 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13f70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13f80 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13f90 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
13fa0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13fb0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
13fc0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
13fd0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
13fe0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13ff0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14000 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
14010 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14020 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
14030 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
14040 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
14050 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
14060 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
14070 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
14080 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
14090 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
140a0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
140b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
140c0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
140d0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
140e0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
140f0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
14100 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
14110 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
14120 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14130 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14140 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14150 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14160 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14170 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14180 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
14190 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
141a0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
141b0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
141c0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
141d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
141e0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
141f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14200 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
14210 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14220 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14230 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14240 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14250 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14260 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14270 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
14280 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14290 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
142a0 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
142b0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
142c0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
142d0 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
142e0 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
142f0 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
14300 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
14310 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
14320 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14330 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
14340 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
14350 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
14360 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
14370 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
14380 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
14390 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
143a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
143b0 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
143c0 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
143d0 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
143e0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
143f0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
14400 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
14410 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
14420 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
14430 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
14440 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
14450 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
14460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
14470 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
14480 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
14490 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
144a0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
144b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
144c0 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
144d0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
144e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
144f0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
14500 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14510 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
14520 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14530 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14540 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14550 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
14560 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
14570 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
14580 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
14590 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
145a0 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
145b0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
145c0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
145d0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
145e0 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
145f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14600 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
14610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14620 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
14630 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14640 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14650 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
14660 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14670 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14680 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14690 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
146a0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
146b0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
146c0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
146d0 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
146e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
146f0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
14700 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14720 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14730 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
14740 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14750 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
14760 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
14770 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
14780 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
14790 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
147a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
147b0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
147c0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
147d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
147e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
147f0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
14800 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
14810 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
14820 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
14830 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
14840 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
14850 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
14860 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
14870 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
14880 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
14890 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
148a0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
148b0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
148c0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
148d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
148e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
148f0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
14900 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
14910 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
14920 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14930 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14940 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
14950 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
14960 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14970 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14980 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14990 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
149a0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
149b0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
149c0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
149d0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
149e0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
149f0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
14a00 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14a10 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
14a20 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
14a30 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
14a40 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
14a50 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
14a60 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
14a70 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14a80 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14a90 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14aa0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14ab0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14ac0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14ad0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14ae0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
14af0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
14b00 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
14b10 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
14b20 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
14b30 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
14b40 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
14b50 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
14b60 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
14b70 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14b80 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14b90 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14ba0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14bb0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14bc0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14bd0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14be0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14bf0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
14c00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14c10 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
14c20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c30 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
14c40 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14c50 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
14c60 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
14c70 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14c80 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14c90 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
14ca0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
14cb0 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
14cc0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14cd0 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
14ce0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
14cf0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
14d00 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14d10 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
14d20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
14d30 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
14d40 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
14d50 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14d60 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14d70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14d80 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14d90 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14da0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14db0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14dc0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14dd0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14de0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14df0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14e00 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14e10 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14e20 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14e30 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14e40 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14e50 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14e60 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14e70 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14e80 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14e90 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14ea0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14eb0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
14ec0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14ed0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14ee0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
14ef0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
14f00 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
14f10 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
14f20 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
14f30 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
14f40 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14f50 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
14f60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14f70 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14f80 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14f90 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14fa0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14fb0 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
14fc0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
14fd0 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
14fe0 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
14ff0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
15000 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
15010 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
15020 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
15030 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
15040 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
15050 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
15060 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
15070 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15080 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
15090 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
150a0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
150b0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
150c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
150d0 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
150e0 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
150f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
15100 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
15110 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
15120 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
15130 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15140 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15150 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
15160 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
15170 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
15180 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
15190 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
151a0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
151b0 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
151c0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
151d0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
151e0 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
151f0 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
15200 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
15210 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
15220 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
15230 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
15240 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
15250 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
15260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15270 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
15280 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15290 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
152a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
152b0 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
152c0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
152d0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
152e0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
152f0 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
15300 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
15310 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
15320 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
15330 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
15340 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
15350 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
15360 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
15370 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15380 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
15390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
153a0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
153b0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
153c0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
153d0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
153e0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
153f0 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
15400 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15410 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
15420 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15430 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
15440 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
15450 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
15460 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
15470 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
15480 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
15490 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
154a0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
154b0 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
154c0 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
154d0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
154e0 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
154f0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
15500 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
15510 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
15520 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15530 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
15540 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15550 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
15560 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15570 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
15580 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15590 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
155a0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
155b0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
155c0 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
155d0 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
155e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
155f0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
15600 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
15610 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15620 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
15630 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
15640 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
15650 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
15660 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
15670 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
15680 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
15690 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
156a0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
156b0 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
156c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
156d0 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
156e0 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
156f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
15700 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
15710 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
15720 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
15730 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
15740 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
15750 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
15760 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
15770 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
15780 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
15790 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
157a0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
157b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
157c0 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
157d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
157e0 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
157f0 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
15800 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
15810 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
15820 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
15830 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
15840 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
15850 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
15860 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
15870 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
15880 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15890 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
158a0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
158b0 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
158c0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
158d0 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
158e0 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
158f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15900 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
15910 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
15920 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
15930 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
15940 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
15950 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
15960 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
15970 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15980 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
15990 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
159a0 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
159b0 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
159c0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
159d0 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
159e0 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
159f0 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15a00 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
15a10 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
15a20 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15a30 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
15a40 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
15a50 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
15a60 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
15a70 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15a80 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15a90 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15aa0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15ab0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15ac0 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15ad0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15ae0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15af0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15b00 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15b10 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
15b20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15b30 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
15b40 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
15b50 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
15b60 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
15b70 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
15b80 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
15b90 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
15ba0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15bb0 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15bc0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15bd0 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15be0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15bf0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15c00 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15c10 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15c20 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15c30 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
15c40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15c50 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
15c60 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15c70 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
15c80 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15c90 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15ca0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
15cb0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15cc0 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
15cd0 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
15ce0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
15cf0 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
15d00 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
15d10 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
15d20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15d30 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
15d40 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
15d50 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
15d60 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
15d70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
15d80 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
15d90 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
15da0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
15db0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15dc0 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
15dd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15de0 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
15df0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15e00 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
15e10 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15e20 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15e30 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
15e40 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
15e50 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
15e60 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
15e70 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
15e80 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
15e90 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
15ea0 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
15eb0 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
15ec0 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
15ed0 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
15ee0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15ef0 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
15f00 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
15f10 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
15f20 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
15f30 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
15f40 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
15f50 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
15f60 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
15f70 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
15f80 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
15f90 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
15fa0 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
15fb0 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
15fc0 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
15fd0 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
15fe0 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
15ff0 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
16000 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ue..** </dl>.*/.
16010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16020 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
16030 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
16040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16050 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
16060 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
16070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16080 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
16090 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
160a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
160b0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
160c0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
160d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
160e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
160f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
16100 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
16110 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16120 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16130 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16140 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
16150 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
16160 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
16170 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16180 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
16190 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
161a0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
161b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
161c0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
161d0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
161e0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
161f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16200 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16210 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
16220 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
16230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16240 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
16250 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
16260 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
16270 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16280 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
16290 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
162a0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
162b0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
162c0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
162d0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
162e0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
162f0 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
16300 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16310 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
16320 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16330 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16340 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
16350 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16360 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16370 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
16380 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
16390 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
163a0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
163b0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
163c0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
163d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
163e0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
163f0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16400 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16410 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
16420 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
16430 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
16440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16450 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
16460 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
16470 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
16480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16490 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
164a0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
164b0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
164c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
164d0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
164e0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
164f0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16500 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16510 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
16520 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
16530 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
16540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16550 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16560 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
16570 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
16580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16590 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
165a0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
165b0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
165c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
165d0 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
165e0 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
165f0 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
16600 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
16610 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
16620 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
16630 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
16640 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
16650 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
16660 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
16670 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16680 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
16690 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
166a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
166b0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
166c0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
166d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
166e0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
166f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
16700 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
16710 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
16720 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
16730 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16740 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
16750 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
16760 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
16770 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
16780 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
16790 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
167a0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
167b0 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
167c0 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
167d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
167e0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
167f0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
16800 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
16810 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
16820 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
16830 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
16840 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
16850 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
16860 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
16870 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
16880 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
16890 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
168a0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
168b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
168c0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
168d0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
168e0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
168f0 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
16900 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
16910 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16920 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
16930 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
16940 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
16950 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
16960 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
16970 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
16980 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
16990 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
169a0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
169b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
169c0 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
169d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
169e0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
169f0 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
16a00 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
16a10 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
16a20 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
16a30 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
16a40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
16a50 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
16a60 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
16a70 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
16a80 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
16a90 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
16aa0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
16ab0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
16ac0 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
16ad0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
16ae0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
16af0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
16b00 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
16b10 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
16b20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
16b30 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
16b40 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
16b50 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
16b60 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
16b70 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
16b80 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
16b90 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
16ba0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16bb0 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
16bc0 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
16bd0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
16be0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
16bf0 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
16c00 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
16c10 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
16c20 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
16c30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16c40 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16c50 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
16c60 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
16c70 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
16c80 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
16c90 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
16ca0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
16cb0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
16cc0 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
16cd0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
16ce0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
16cf0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
16d00 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
16d10 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
16d20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
16d30 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16d40 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16d50 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
16d60 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
16d70 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
16d80 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
16d90 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
16da0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
16db0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
16dc0 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
16dd0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16de0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16df0 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
16e00 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16e10 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
16e20 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
16e30 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16e40 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16e50 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
16e60 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16e70 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16e80 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16e90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16ea0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16eb0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16ec0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
16ed0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
16ee0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
16ef0 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
16f00 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
16f10 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
16f20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
16f30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16f40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16f50 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16f60 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16f70 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16f80 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16f90 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
16fa0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
16fb0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
16fc0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
16fd0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
16fe0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
16ff0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17000 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17010 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17020 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17030 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17040 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17050 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
17060 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
17070 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17080 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17090 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
170a0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
170b0 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
170c0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
170d0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
170e0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
170f0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17100 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17110 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17120 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17130 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17140 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
17150 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
17160 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
17170 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
17180 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17190 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
171a0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
171b0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
171c0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
171d0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
171e0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
171f0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17200 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17210 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17220 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17230 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17240 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
17250 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
17260 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17270 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17280 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
17290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
172a0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
172b0 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
172c0 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
172d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
172e0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
172f0 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
17300 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
17310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17320 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17330 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
17340 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
17350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
17360 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
17370 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
17380 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
17390 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
173a0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
173b0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
173c0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
173d0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
173e0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
173f0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
17400 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
17410 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
17420 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
17430 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
17440 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
17450 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
17460 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
17470 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
17480 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
17490 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
174a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
174b0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
174c0 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
174d0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
174e0 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
174f0 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
17500 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
17510 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
17520 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
17530 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
17540 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
17550 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
17560 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
17570 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
17580 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
17590 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
175a0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
175b0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
175c0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
175d0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
175e0 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
175f0 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
17600 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
17610 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
17620 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
17630 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
17640 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
17650 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
17660 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
17670 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
17680 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
17690 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
176a0 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
176b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
176c0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
176d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
176e0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
176f0 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
17700 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
17710 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
17720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17730 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
17740 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
17750 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
17760 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
17770 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
17780 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
17790 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
177a0 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
177b0 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
177c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
177d0 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
177e0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
177f0 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
17800 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
17810 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
17820 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
17830 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
17840 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
17850 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
17860 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
17870 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
17880 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
17890 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
178a0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
178b0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
178c0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
178d0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
178e0 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
178f0 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
17900 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
17910 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17920 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
17930 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
17940 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
17950 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
17960 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
17970 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
17980 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
17990 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
179a0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
179b0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
179c0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
179d0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
179e0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
179f0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
17a00 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
17a10 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
17a20 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
17a30 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
17a40 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
17a50 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
17a60 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
17a70 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
17a80 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
17a90 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
17aa0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
17ab0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
17ac0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
17ad0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
17ae0 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
17af0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17b00 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
17b10 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
17b20 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
17b30 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
17b40 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
17b50 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
17b60 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
17b70 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
17b80 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
17b90 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
17ba0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
17bb0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
17bc0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
17bd0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
17be0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
17bf0 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
17c00 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
17c10 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
17c20 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
17c30 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
17c40 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
17c50 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
17c60 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
17c70 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
17c80 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
17c90 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
17ca0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
17cb0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
17cc0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
17cd0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
17ce0 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
17cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
17d00 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
17d10 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17d20 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
17d30 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
17d40 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
17d50 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
17d60 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
17d70 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17d80 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
17d90 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17da0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
17db0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
17dc0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
17dd0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
17de0 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
17df0 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
17e00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
17e10 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17e20 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
17e30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17e40 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
17e50 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
17e60 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
17e70 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
17e80 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
17e90 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
17ea0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
17eb0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a  d, inserted or.*
17ec0 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  * deleted by the
17ed0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
17ee0 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
17ef0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
17f00 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f  E.** statement o
17f10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
17f20 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
17f30 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20  ied by the only 
17f40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45  parameter..** ^E
17f50 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
17f60 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
17f70 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
17f80 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c  t modify the val
17f90 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
17fa0 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  y this function.
17fb0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61  .**.** ^Only cha
17fc0 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74  nges made direct
17fd0 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54  ly by the INSERT
17fe0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
17ff0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
18000 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d  .** considered -
18010 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   auxiliary chang
18020 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52  es caused by [CR
18030 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
18040 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66  riggers], .** [f
18050 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
18060 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d  ns] or [REPLACE]
18070 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
18080 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63  lution are not c
18090 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43  ounted..** .** C
180a0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
180b0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
180c0 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e  epted by .** [IN
180d0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
180e0 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72   | INSTEAD OF tr
180f0 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20  iggers] are not 
18100 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61  counted. ^The va
18110 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  lue .** returned
18120 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e   by sqlite3_chan
18130 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c  ges() immediatel
18140 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52  y after an INSER
18150 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a  T, UPDATE or .**
18160 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
18170 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20  t run on a view 
18180 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20  is always zero. 
18190 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
181a0 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61  e to real .** ta
181b0 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  bles are counted
181c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61  ..**.** Things a
181d0 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61  re more complica
181e0 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74  ted if the sqlit
181f0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
18200 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63  ction is.** exec
18210 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69  uted while a tri
18220 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20  gger program is 
18230 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61  running. This ma
18240 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a  y happen if the.
18250 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
18260 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
18270 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72  QL function], or
18280 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63   if some other c
18290 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
182a0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69  ion invokes sqli
182b0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69  te3_changes() di
182c0 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61  rectly. Essentia
182d0 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  lly:.** .** <ul>
182e0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66  .**   <li> ^(Bef
182f0 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74  ore entering a t
18300 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74  rigger program t
18310 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18320 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73  d by.**        s
18330 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18340 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76   function is sav
18350 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72  ed. After the tr
18360 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a  igger program .*
18370 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e  *        has fin
18380 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69  ished, the origi
18390 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73  nal value is res
183a0 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20  tored.)^.** .** 
183b0 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20    <li> ^(Within 
183c0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
183d0 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55  m each INSERT, U
183e0 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45  PDATE and DELETE
183f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74   .**        stat
18400 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76  ement sets the v
18410 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
18420 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18430 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70  () .**        up
18440 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73  on completion as
18450 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72   normal. Of cour
18460 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77  se, this value w
18470 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  ill not include 
18480 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63  .**        any c
18490 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64  hanges performed
184a0 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73   by sub-triggers
184b0 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33  , as the sqlite3
184c0 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
184d0 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c        value will
184e0 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65   be saved and re
184f0 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63  stored after eac
18500 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61  h sub-trigger ha
18510 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c  s run.)^.** </ul
18520 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d  >.** .** ^This m
18530 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65  eans that if the
18540 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66   changes() SQL f
18550 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69  unction (or simi
18560 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20  lar) is used.** 
18570 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53  by the first INS
18580 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
18590 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
185a0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
185b0 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73  , it .** returns
185c0 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65   the value as se
185d0 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69  t when the calli
185e0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67  ng statement beg
185f0 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  an executing..**
18600 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20   ^If it is used 
18610 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72  by the second or
18620 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68   subsequent such
18630 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
18640 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20  n a trigger .** 
18650 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c  program, the val
18660 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c  ue returned refl
18670 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ects the number 
18680 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
18690 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76   by the .** prev
186a0 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44  ious INSERT, UPD
186b0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
186c0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
186d0 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
186e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
186f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
18700 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
18710 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
18720 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
18730 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
18740 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
18750 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
18760 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
18770 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
18780 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
18790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
187a0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
187b0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
187c0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
187d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
187e0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
187f0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
18800 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
18810 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
18820 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
18830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
18840 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
18850 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d  ws Modified.** M
18860 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
18870 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
18880 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
18890 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
188a0 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d  rows inserted, m
188b0 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65  odified or.** de
188c0 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e  leted by all [IN
188d0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20  SERT], [UPDATE] 
188e0 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
188f0 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64  ements completed
18900 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61  .** since the da
18910 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18920 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e  n was opened, in
18930 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78  cluding those ex
18940 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72  ecuted as.** par
18950 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f  t of trigger pro
18960 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e  grams. ^Executin
18970 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
18980 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
18990 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66  t.** does not af
189a0 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72  fect the value r
189b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
189c0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
189d0 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e  ()..** .** ^Chan
189e0 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74  ges made as part
189f0 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   of [foreign key
18a00 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e   actions] are in
18a10 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a  cluded in the.**
18a20 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73   count, but thos
18a30 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  e made as part o
18a40 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
18a50 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
18a60 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61  are.** not. ^Cha
18a70 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
18a80 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
18a90 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f  ted by INSTEAD O
18aa0 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61  F triggers .** a
18ab0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
18ac0 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  ** .** See also 
18ad0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
18ae0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
18af0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
18b00 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
18b10 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
18b20 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
18b30 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
18b40 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
18b50 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
18b60 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
18b70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18b80 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
18b90 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18ba0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
18bb0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
18bc0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
18bd0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
18be0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
18bf0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18c00 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
18c10 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
18c20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
18c30 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
18c40 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
18c50 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
18c60 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
18c70 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
18c80 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
18c90 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
18ca0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
18cb0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
18cc0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
18cd0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
18ce0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
18cf0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
18d00 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
18d10 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
18d20 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
18d30 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
18d40 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
18d50 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
18d60 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
18d70 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
18d80 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
18d90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
18da0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
18db0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
18dc0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
18dd0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
18de0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
18df0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
18e00 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
18e10 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
18e20 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
18e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18e40 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
18e50 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
18e60 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
18e70 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18e80 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
18e90 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
18ea0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
18eb0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
18ec0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
18ed0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18ee0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
18ef0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
18f00 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
18f10 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
18f20 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
18f30 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
18f40 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
18f50 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
18f60 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
18f70 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
18f80 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
18f90 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
18fa0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
18fb0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
18fc0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
18fd0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
18fe0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
18ff0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
19000 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
19010 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
19020 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
19030 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
19040 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
19050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
19060 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
19070 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
19080 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
19090 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
190a0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
190b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
190c0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
190d0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
190e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
190f0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
19100 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
19110 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
19120 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
19130 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
19140 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
19150 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
19160 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
19170 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
19180 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
19190 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
191a0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
191b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
191c0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
191d0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
191e0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
191f0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
19200 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
19210 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
19220 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
19230 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
19240 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19250 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
19260 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
19270 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
19280 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
19290 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
192a0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
192b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
192c0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
192d0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
192e0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
192f0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
19300 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
19310 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
19320 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
19330 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
19340 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
19350 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
19360 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
19370 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
19380 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
19390 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
193a0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
193b0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
193c0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
193d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
193e0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
193f0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
19400 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
19410 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
19420 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
19430 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
19440 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
19450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
19460 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
19470 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
19480 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
19490 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
194a0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
194b0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
194c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
194d0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
194e0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
194f0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
19500 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
19510 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
19520 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
19530 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
19540 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
19550 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
19560 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
19570 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
19580 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
19590 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
195a0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
195b0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
195c0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
195d0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
195e0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
195f0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
19600 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
19610 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
19620 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
19630 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
19640 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
19650 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
19660 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
19670 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
19680 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
19690 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
196a0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
196b0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
196c0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
196d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
196e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
196f0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
19700 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
19710 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
19720 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
19730 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
19740 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
19750 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
19760 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
19770 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
19780 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
19790 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
197a0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
197b0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
197c0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
197d0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
197e0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
197f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
19800 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
19810 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
19820 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19830 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
19840 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
19850 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
19860 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
19870 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
19880 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
19890 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
198a0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
198b0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
198c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
198d0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
198e0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
198f0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
19900 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
19910 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
19920 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
19930 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
19940 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
19950 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
19960 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
19970 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
19980 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
19990 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
199a0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
199b0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
199c0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
199d0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
199e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
199f0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
19a00 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
19a10 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
19a20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
19a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19a40 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
19a50 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
19a60 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
19a70 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
19a80 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61  {busy-handler ca
19a90 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61  llback} {busy ha
19aa0 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  ndler}.** METHOD
19ab0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19ac0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73  ^The sqlite3_bus
19ad0 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29  y_handler(D,X,P)
19ae0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
19af0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19b00 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68  n X.** that migh
19b10 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
19b20 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
19b30 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
19b40 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61  mpt is made to a
19b50 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65  ccess a database
19b60 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65   table associate
19b70 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62  d with.** [datab
19b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19b90 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74  D when another t
19ba0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
19bb0 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c  ess has the tabl
19bc0 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65  e locked..** The
19bd0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19be0 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63  ndler() interfac
19bf0 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70  e is used to imp
19c00 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74  lement.** [sqlit
19c10 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
19c20 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62  )] and [PRAGMA b
19c30 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a  usy_timeout]..**
19c40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
19c50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
19c60 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
19c70 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75  BUSY].** is retu
19c80 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
19c90 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
19ca0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
19cb0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
19cc0 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
19cd0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
19ce0 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
19cf0 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
19d00 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
19d10 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
19d20 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
19d30 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
19d40 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
19d50 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
19d60 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
19d70 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
19d80 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
19d90 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
19da0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
19db0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
19dc0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
19dd0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
19de0 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
19df0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
19e00 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75   invoked previou
19e10 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65  sly for the same
19e20 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
19e30 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
19e40 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19e50 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
19e60 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
19e70 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
19e80 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
19e90 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
19ea0 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65  BUSY] is returne
19eb0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  d.** to the appl
19ec0 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  ication..** ^If 
19ed0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
19ee0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
19ef0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
19f00 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
19f10 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
19f20 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79  abase and the cy
19f30 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
19f40 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
19f50 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
19f60 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
19f70 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
19f80 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
19f90 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
19fa0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
19fb0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
19fc0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
19fd0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
19fe0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
19ff0 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1a000 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1a010 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1a020 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1a030 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1a040 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  on instead of in
1a050 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62  voking the .** b
1a060 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1a070 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1a080 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1a090 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1a0a0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1a0b0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1a0c0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1a0d0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1a0e0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1a0f0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1a100 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1a110 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1a120 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1a130 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1a140 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1a150 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1a160 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1a170 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1a180 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1a190 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1a1a0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1a1b0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1a1c0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1a1d0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1a1e0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1a1f0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1a200 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1a210 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1a220 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1a230 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1a240 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1a250 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1a260 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1a270 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1a280 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1a290 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1a2a0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1a2b0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1a2c0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1a2d0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1a2e0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1a2f0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1a300 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1a310 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  L..**.** ^(There
1a320 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1a330 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1a340 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1a350 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1a360 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1a370 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1a380 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1a390 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1a3a0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1a3b0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1a3c0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1a3d0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1a3e0 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  * or evaluating 
1a3f0 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1a400 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61  eout=N] will cha
1a410 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  nge the.** busy 
1a420 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73  handler and thus
1a430 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69   clear any previ
1a440 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68  ously set busy h
1a450 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
1a460 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1a470 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
1a480 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
1a490 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
1a4a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a4b0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1a4c0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1a4d0 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  r.  In other wor
1a4e0 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ds,.** the busy 
1a4f0 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72  handler is not r
1a500 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73  eentrant.  Any s
1a510 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
1a520 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
1a530 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
1a540 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
1a550 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
1a560 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1a570 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
1a580 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1a590 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
1a5a0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1a5b0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1a5c0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a5d0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1a5e0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1a5f0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1a600 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1a610 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1a620 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a630 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1a640 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1a650 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1a660 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1a670 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1a680 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1a690 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1a6a0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1a6b0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1a6c0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1a6d0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1a6e0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1a6f0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1a700 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1a710 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1a720 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1a730 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1a740 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1a750 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1a760 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1a770 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1a780 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1a790 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1a7a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1a7b0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1a7c0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1a7d0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1a7e0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1a7f0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1a800 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1a810 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1a820 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1a830 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1a840 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1a850 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a860 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1a870 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1a880 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1a890 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1a8a0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1a8b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a8c0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1a8d0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1a8e0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1a8f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1a900 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1a910 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1a920 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1a930 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t].*/.int sqlite
1a940 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1a950 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1a960 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a970 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1a980 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1a990 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1a9a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1a9b0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1a9c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1a9d0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1a9e0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1a9f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1aa00 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1aa10 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1aa20 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1aa30 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1aa40 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1aa50 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1aa60 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1aa70 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1aa80 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1aa90 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1aaa0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1aab0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1aac0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1aad0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1aae0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1aaf0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1ab00 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1ab10 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1ab20 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1ab30 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1ab40 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1ab50 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1ab60 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1ab70 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1ab80 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1ab90 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1aba0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1abb0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1abc0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1abd0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1abe0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1abf0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1ac00 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1ac10 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1ac20 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1ac30 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1ac40 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1ac50 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1ac60 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1ac70 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1ac80 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1ac90 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1aca0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1acb0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1acc0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1acd0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1ace0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1acf0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1ad00 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1ad10 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1ad20 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1ad30 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1ad40 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1ad50 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1ad60 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1ad70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1ad80 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1ad90 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1ada0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1adb0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1adc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1add0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1ade0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1adf0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1ae00 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1ae10 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1ae20 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1ae30 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1ae40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1ae50 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1ae60 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1ae70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1ae80 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1ae90 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1aea0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1aeb0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1aec0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1aed0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1aee0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1aef0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1af00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1af10 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1af20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1af30 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1af40 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1af50 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1af60 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1af70 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1af80 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1af90 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1afa0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1afb0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1afc0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1afd0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1afe0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1aff0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1b000 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1b010 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1b020 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1b030 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1b040 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b050 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1b060 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1b070 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1b080 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b090 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1b0a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b0b0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1b0c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1b0d0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1b0e0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1b0f0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1b100 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1b110 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1b120 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1b130 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b140 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1b150 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b160 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1b170 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b180 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1b190 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1b1a0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1b1b0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1b1c0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1b1d0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1b1e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1b1f0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1b200 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1b210 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1b220 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1b230 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1b240 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1b250 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1b260 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1b270 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1b280 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1b290 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1b2a0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1b2b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b2c0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1b2d0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1b2e0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1b2f0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1b300 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1b310 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1b320 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1b330 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1b340 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1b350 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1b360 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1b370 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1b380 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1b390 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1b3a0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1b3b0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1b3c0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1b3d0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1b3e0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1b3f0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1b400 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1b410 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1b420 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1b430 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1b440 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1b450 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1b460 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1b470 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1b480 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1b490 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b4a0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1b4b0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1b4c0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1b4d0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1b4e0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1b4f0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1b500 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1b510 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1b520 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1b530 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1b540 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1b550 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1b560 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1b570 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1b580 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1b590 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1b5a0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1b5b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1b5c0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1b5d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b5e0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1b5f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1b600 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1b610 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1b620 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1b630 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1b640 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1b650 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1b660 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1b670 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1b680 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1b690 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1b6a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1b6b0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1b6c0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1b6d0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1b6e0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1b6f0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1b700 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1b710 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1b720 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1b730 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1b740 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1b750 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1b760 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1b770 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1b780 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1b790 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1b7a0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1b7b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b7c0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1b7d0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1b7e0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1b7f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1b800 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1b810 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65  ibrary..** These
1b820 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73   routines unders
1b830 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65  tand most of the
1b840 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d   common K&R form
1b850 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a  atting options,.
1b860 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64  ** plus some add
1b870 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e  itional non-stan
1b880 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65  dard formats, de
1b890 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a  tailed below..**
1b8a0 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20   Note that some 
1b8b0 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63  of the more obsc
1b8c0 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  ure formatting o
1b8d0 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65  ptions from rece
1b8e0 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20  nt.** C-library 
1b8f0 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d  standards are om
1b900 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20  itted from this 
1b910 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
1b920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b930 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1b940 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1b950 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1b960 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1b970 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1b980 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1b990 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b9a0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1b9b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1b9c0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1b9d0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1b9e0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1b9f0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1ba00 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1ba10 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1ba20 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1ba30 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1ba40 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1ba50 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1ba60 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1ba70 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1ba80 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1ba90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1baa0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1bab0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1bac0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1bad0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1bae0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1baf0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1bb00 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1bb10 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1bb20 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1bb30 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1bb40 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1bb50 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1bb60 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1bb70 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1bb80 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1bb90 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1bba0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1bbb0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1bbc0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1bbd0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1bbe0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1bbf0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1bc00 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1bc10 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1bc20 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1bc30 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1bc40 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1bc50 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1bc60 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1bc70 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1bc80 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1bc90 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1bca0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1bcb0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1bcc0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1bcd0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1bce0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1bcf0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1bd00 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1bd10 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1bd20 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1bd30 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1bd40 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1bd50 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1bd60 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1bd70 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1bd80 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1bd90 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1bda0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1bdb0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1bdc0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1bdd0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1bde0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1bdf0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1be00 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1be10 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1be20 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1be30 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1be40 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1be50 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1be60 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1be70 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1be80 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1be90 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1bea0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1beb0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1bec0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1bed0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1bee0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1bef0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1bf00 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1bf10 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1bf20 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1bf30 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1bf40 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1bf50 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1bf60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1bf70 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1bf80 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1bf90 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1bfa0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1bfb0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1bfc0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1bfd0 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f   "%w" and "%z" o
1bfe0 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1bff0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1c000 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1c010 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1c020 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1c030 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1c040 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1c050 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1c060 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1c070 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1c080 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1c090 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1c0a0 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1c0b0 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1c0c0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1c0d0 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1c0e0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1c0f0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1c100 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1c110 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1c120 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1c130 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1c140 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1c150 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1c160 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1c170 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c180 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1c190 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1c1a0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1c1b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1c1c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1c1d0 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1c1e0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1c1f0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1c200 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c210 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c220 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1c230 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1c240 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c250 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1c260 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1c270 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1c280 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1c290 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1c2a0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1c2b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c2c0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1c2d0 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1c2e0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1c2f0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1c300 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1c310 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1c320 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1c330 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1c340 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c350 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1c360 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1c370 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1c380 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1c390 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c3a0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1c3b0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1c3c0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1c3d0 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1c3e0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1c3f0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1c400 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c410 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1c420 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1c430 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1c440 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1c450 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c460 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1c470 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1c480 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1c490 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1c4a0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1c4b0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1c4c0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1c4d0 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1c4e0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1c4f0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1c500 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1c510 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1c520 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1c530 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1c540 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1c550 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1c560 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1c570 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1c580 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1c590 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1c5a0 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1c5b0 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1c5c0 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1c5d0 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1c5e0 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1c5f0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1c600 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1c610 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1c620 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c630 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1c640 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1c650 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1c660 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1c670 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1c680 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1c690 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1c6a0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1c6b0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1c6c0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c6d0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1c6e0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1c6f0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1c700 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1c710 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1c720 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1c730 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1c740 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1c750 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f  ** ^(The "%w" fo
1c760 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1c770 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63  is like "%q" exc
1c780 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65  ept that it expe
1c790 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e  cts to.** be con
1c7a0 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f  tained within do
1c7b0 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74  uble-quotes inst
1c7c0 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75  ead of single qu
1c7d0 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20  otes, and it.** 
1c7e0 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62  escapes the doub
1c7f0 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
1c800 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1c810 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a  e single-quote.*
1c820 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20  * character.)^  
1c830 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1c840 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ing option is in
1c850 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c  tended for safel
1c860 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  y inserting.** t
1c870 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1c880 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e  names into a con
1c890 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61  structed SQL sta
1c8a0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tement..**.** ^(
1c8b0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1c8c0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1c8d0 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1c8e0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1c8f0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1c900 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1c910 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1c920 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1c930 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1c940 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1c950 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1c960 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
1c970 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1c980 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1c990 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1c9a0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1c9b0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1c9c0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1c9d0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1c9e0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1c9f0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1ca00 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1ca10 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1ca20 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1ca30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ca40 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1ca50 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1ca60 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1ca70 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1ca80 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1ca90 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1caa0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1cab0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1cac0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1cad0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1cae0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1caf0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1cb00 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1cb10 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1cb20 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1cb30 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1cb40 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1cb50 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1cb60 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1cb70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cb80 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1cb90 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1cba0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1cbb0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1cbc0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1cbd0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1cbe0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1cbf0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1cc00 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1cc10 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1cc20 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1cc30 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1cc40 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1cc50 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1cc60 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1cc70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cc80 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1cc90 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1cca0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1ccb0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1ccc0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1ccd0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1cce0 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1ccf0 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1cd00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1cd10 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1cd20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1cd30 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1cd40 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1cd50 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1cd60 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1cd70 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1cd80 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1cd90 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1cda0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1cdb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1cdc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cdd0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1cde0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1cdf0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1ce00 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1ce10 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1ce20 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1ce30 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1ce40 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1ce50 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1ce60 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1ce70 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ce80 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1ce90 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1cea0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1ceb0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1cec0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1ced0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1cee0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1cef0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1cf00 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1cf10 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1cf20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1cf30 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1cf40 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1cf50 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1cf60 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1cf70 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1cf80 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1cf90 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1cfa0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1cfb0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1cfc0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1cfd0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1cfe0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1cff0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1d000 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d010 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1d020 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1d030 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1d040 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1d050 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1d060 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1d070 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1d080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1d090 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1d0a0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1d0b0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1d0c0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1d0d0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1d0e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d0f0 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1d100 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1d110 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d120 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1d130 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1d140 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1d150 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1d160 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1d170 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1d180 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1d190 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1d1a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1d1b0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1d1c0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1d1d0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1d1e0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1d1f0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1d200 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1d210 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1d220 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1d230 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1d240 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1d250 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1d260 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1d270 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1d280 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1d290 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1d2a0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1d2b0 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1d2c0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1d2d0 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1d2e0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1d2f0 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1d300 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1d310 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1d320 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1d330 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1d340 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1d350 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1d360 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1d370 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1d380 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1d390 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1d3a0 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1d3b0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1d3c0 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1d3d0 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1d3e0 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1d3f0 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1d400 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1d410 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1d420 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1d430 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1d440 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1d450 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d460 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1d470 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1d480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1d490 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
1d4a0 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
1d4b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d4c0 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
1d4d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1d4e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
1d4f0 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
1d500 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
1d510 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1d520 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
1d530 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
1d540 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
1d550 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
1d560 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1d570 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
1d580 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
1d590 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
1d5a0 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
1d5b0 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
1d5c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
1d5d0 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
1d5e0 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
1d5f0 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
1d600 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
1d610 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
1d620 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1d630 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
1d640 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
1d650 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
1d660 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1d670 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1d680 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1d690 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
1d6a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
1d6b0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1d6c0 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
1d6d0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
1d6e0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1d6f0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1d700 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1d710 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1d720 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1d730 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1d740 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1d750 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1d760 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1d770 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1d780 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1d790 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1d7a0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1d7b0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1d7c0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1d7d0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1d7e0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1d7f0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1d800 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1d810 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1d820 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1d830 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1d840 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1d850 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1d860 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1d870 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1d880 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1d890 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1d8a0 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1d8b0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1d8c0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1d8d0 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1d8e0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1d8f0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1d900 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1d910 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1d920 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1d930 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1d940 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1d950 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1d960 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1d970 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1d980 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1d990 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1d9a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1d9b0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1d9c0 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1d9d0 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1d9e0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1d9f0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1da00 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1da10 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1da20 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1da30 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1da40 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1da50 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1da60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1da70 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1da80 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1da90 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1daa0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1dab0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1dac0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dad0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1dae0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1daf0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1db00 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1db10 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1db20 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1db30 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1db40 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1db50 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1db60 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1db70 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1db80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1db90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1dba0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1dbb0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1dbc0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1dbd0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
1dbe0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1dbf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1dc00 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1dc10 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1dc20 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
1dc30 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1dc40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1dc50 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74  ee(void*);.sqlit
1dc60 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
1dc70 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
1dc80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1dc90 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1dca0 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1dcb0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1dcc0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1dcd0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1dce0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1dcf0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1dd00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1dd10 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1dd20 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1dd30 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1dd40 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1dd50 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1dd60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1dd70 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1dd80 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1dd90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1dda0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1ddb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1ddc0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1ddd0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1dde0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1ddf0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1de00 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1de10 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1de20 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1de30 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1de40 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1de50 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1de60 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1de70 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1de80 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1de90 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1dea0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1deb0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1dec0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ded0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1dee0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1def0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1df00 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1df10 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1df20 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1df30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1df40 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1df50 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1df60 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1df70 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1df80 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1df90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1dfa0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1dfb0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1dfc0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1dfd0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1dfe0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1dff0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e000 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1e010 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1e020 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1e030 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1e040 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1e050 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1e060 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1e070 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e080 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1e090 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1e0a0 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1e0b0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
1e0c0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1e0d0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
1e0e0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
1e0f0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1e100 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
1e110 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
1e120 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
1e130 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
1e140 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
1e150 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
1e160 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
1e170 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
1e180 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
1e190 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
1e1a0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
1e1b0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
1e1c0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1e1d0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
1e1e0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
1e1f0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
1e200 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
1e210 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1e220 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1e230 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1e240 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1e250 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1e260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1e270 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1e280 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1e290 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1e2a0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1e2b0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1e2c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1e2d0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1e2e0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1e2f0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1e300 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
1e310 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
1e320 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
1e330 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
1e340 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
1e350 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
1e360 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
1e370 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
1e380 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
1e390 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
1e3a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
1e3b0 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
1e3c0 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
1e3d0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1e3e0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1e3f0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
1e400 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
1e410 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1e420 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1e430 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
1e440 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
1e450 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
1e460 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
1e470 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
1e480 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
1e490 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1e4a0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1e4b0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1e4c0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1e4d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1e4e0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1e4f0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1e500 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1e510 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1e520 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1e530 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1e540 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1e550 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
1e560 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1e570 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1e580 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
1e590 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e5a0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
1e5b0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1e5c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
1e5d0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
1e5e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
1e5f0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
1e600 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1e610 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
1e620 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
1e630 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
1e640 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e650 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1e660 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
1e670 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
1e680 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e690 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
1e6a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e6b0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
1e6c0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
1e6d0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
1e6e0 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
1e6f0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
1e700 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
1e710 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
1e720 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
1e730 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e740 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
1e750 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
1e760 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
1e770 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1e780 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
1e790 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1e7a0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
1e7b0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
1e7c0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
1e7d0 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
1e7e0 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
1e7f0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
1e800 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
1e810 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
1e820 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
1e830 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
1e840 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
1e850 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
1e860 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
1e870 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
1e880 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
1e890 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e8a0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
1e8b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1e8c0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
1e8d0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
1e8e0 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
1e8f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1e900 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1e910 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1e920 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
1e930 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e940 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1e950 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1e960 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1e970 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e980 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
1e990 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
1e9a0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
1e9b0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
1e9c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1e9d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1e9e0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
1e9f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ea00 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1ea10 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1ea20 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
1ea30 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1ea40 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1ea50 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
1ea60 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
1ea70 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
1ea80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
1ea90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1eaa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eab0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1eac0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
1ead0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
1eae0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1eaf0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
1eb00 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
1eb10 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
1eb20 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1eb30 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
1eb40 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
1eb50 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1eb60 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
1eb70 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
1eb80 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
1eb90 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
1eba0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
1ebb0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
1ebc0 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
1ebd0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1ebe0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
1ebf0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
1ec00 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
1ec10 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1ec20 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
1ec30 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1ec40 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
1ec50 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
1ec60 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1ec70 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1ec80 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
1ec90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1eca0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
1ecb0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
1ecc0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
1ecd0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
1ece0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1ecf0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
1ed00 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
1ed10 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1ed20 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1ed30 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1ed40 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
1ed50 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
1ed60 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
1ed70 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
1ed80 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
1ed90 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
1eda0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
1edb0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1edc0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
1edd0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1ede0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
1edf0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1ee00 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
1ee10 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
1ee20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
1ee30 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
1ee40 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
1ee50 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
1ee60 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
1ee70 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
1ee80 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
1ee90 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
1eea0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1eeb0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
1eec0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
1eed0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
1eee0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
1eef0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1ef00 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
1ef10 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
1ef20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
1ef30 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
1ef40 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
1ef50 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
1ef60 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
1ef70 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
1ef80 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
1ef90 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
1efa0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
1efb0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
1efc0 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
1efd0 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
1efe0 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
1eff0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
1f000 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
1f010 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
1f020 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
1f030 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
1f040 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
1f050 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
1f060 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
1f070 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
1f080 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
1f090 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
1f0a0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
1f0b0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
1f0c0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1f0d0 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
1f0e0 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
1f0f0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
1f100 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
1f110 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
1f120 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
1f130 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
1f140 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
1f150 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
1f160 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
1f170 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
1f180 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
1f190 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1f1a0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
1f1b0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
1f1c0 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
1f1d0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
1f1e0 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
1f1f0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
1f200 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
1f210 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
1f220 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
1f230 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
1f240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1f250 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
1f260 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
1f270 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f280 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
1f290 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
1f2a0 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
1f2b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
1f2c0 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
1f2d0 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
1f2e0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
1f2f0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
1f300 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
1f310 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f320 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1f330 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1f340 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1f350 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1f360 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1f370 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1f380 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1f390 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1f3a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f3b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1f3c0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1f3d0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1f3e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1f3f0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1f400 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1f410 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1f420 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1f430 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f440 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1f450 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1f460 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1f470 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1f480 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1f490 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1f4a0 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1f4b0 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1f4c0 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1f4d0 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1f4e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1f4f0 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1f500 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1f510 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1f520 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1f530 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1f540 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1f550 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f560 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1f570 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1f580 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1f590 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1f5a0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1f5b0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1f5c0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1f5d0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1f5e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f5f0 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1f600 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1f610 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1f620 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1f630 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1f640 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f650 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1f660 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1f670 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1f680 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f690 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1f6a0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1f6b0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1f6c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1f6d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1f6e0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1f6f0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1f700 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1f710 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1f720 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1f730 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1f740 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f750 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1f760 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1f770 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1f780 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1f790 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1f7a0 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1f7b0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1f7c0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1f7d0 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1f7e0 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1f7f0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1f800 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1f810 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1f820 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1f830 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1f840 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1f850 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1f860 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1f870 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1f880 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66   used as a [conf
1f890 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
1f8a0 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  mode].** returne
1f8b0 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  d from the [sqli
1f8c0 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1f8d0 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1f8e0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1f8f0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1f900 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1f910 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1f920 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1f930 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1f940 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1f950 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1f960 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1f970 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1f980 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1f990 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1f9a0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1f9b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f9c0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1f9d0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1f9e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f9f0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1fa00 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1fa10 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1fa20 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1fa30 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1fa40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1fa50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1fa60 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1fa70 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1fa80 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1fa90 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1faa0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1fab0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1fac0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1fad0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fae0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1faf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1fb00 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1fb10 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1fb20 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1fb30 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1fb40 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1fb50 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1fb60 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1fb70 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1fb80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1fb90 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1fba0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1fbb0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1fbc0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1fbd0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1fbe0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1fbf0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1fc00 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1fc10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fc20 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1fc30 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1fc40 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1fc50 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1fc60 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1fc70 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1fc80 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1fc90 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1fca0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1fcb0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1fcc0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1fcd0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1fce0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1fcf0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1fd00 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1fd10 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1fd20 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1fd30 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1fd40 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1fd50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fd60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1fd70 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1fd80 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1fd90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fda0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1fdb0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1fdc0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1fdd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1fde0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1fdf0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1fe00 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1fe10 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1fe20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fe30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1fe40 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1fe50 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1fe60 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1fe70 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1fe80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fe90 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1fea0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1feb0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1fec0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1fed0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fee0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1fef0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1ff00 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1ff10 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ff20 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ff30 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1ff40 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1ff50 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1ff60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ff70 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ff80 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1ff90 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1ffa0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1ffb0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ffc0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ffd0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1ffe0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1fff0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20000 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20010 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
20020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
20030 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20040 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20050 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20060 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
20070 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
20080 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20090 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
200a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
200b0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
200c0 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
200d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
200e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
200f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20100 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
20110 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
20120 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
20130 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20140 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20150 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
20160 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
20170 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20180 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20190 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
201a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
201b0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
201c0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
201d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
201e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
201f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
20200 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
20210 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
20220 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20240 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
20250 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
20260 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
20270 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
20280 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20290 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
202a0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
202b0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
202c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
202d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
202e0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
202f0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
20300 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
20310 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
20330 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
20340 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
20350 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
20360 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
20370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
20380 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
20390 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
203a0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
203b0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
203c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
203d0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
203e0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
203f0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
20400 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20410 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
20420 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
20430 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
20440 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
20450 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20460 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
20470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20480 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
20490 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
204a0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
204b0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
204c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
204d0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
204e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
204f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20500 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
20510 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
20520 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
20530 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
20540 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20550 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
20560 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
20570 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
20580 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
20590 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
205a0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
205b0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
205c0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
205d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
205e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
205f0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
20600 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
20610 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20620 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20630 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20640 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
20650 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
20660 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20670 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
20680 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20690 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
206a0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
206b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
206c0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
206d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
206e0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
206f0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
20700 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
20710 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
20720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20730 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
20740 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
20750 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
20760 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
20770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20780 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
20790 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
207a0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
207b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
207c0 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
207d0 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
207e0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
207f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
20800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
20810 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
20820 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
20830 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
20840 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  3.**.** These ro
20850 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
20860 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20870 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
20880 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
20890 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
208a0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
208b0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
208c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
208d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
208e0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
208f0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
20900 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
20910 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
20920 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20930 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
20940 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
20950 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
20960 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
20970 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20980 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
20990 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
209a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
209b0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
209c0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
209d0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
209e0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
209f0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
20a00 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
20a10 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
20a20 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
20a30 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
20a40 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
20a50 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
20a60 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
20a70 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
20a80 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
20a90 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
20aa0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
20ab0 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
20ac0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
20ad0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
20ae0 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
20af0 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
20b00 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
20b10 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
20b20 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
20b30 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
20b40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20b50 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
20b60 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
20b70 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
20b80 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
20b90 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
20ba0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
20bb0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
20bc0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
20bd0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
20be0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
20bf0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
20c00 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
20c10 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
20c20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
20c30 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20c40 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
20c50 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
20c60 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
20c70 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
20c80 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
20c90 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
20ca0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
20cb0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
20cc0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
20cd0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
20ce0 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
20cf0 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
20d00 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
20d10 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
20d20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
20d30 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
20d40 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
20d50 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
20d60 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
20d70 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
20d80 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
20d90 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
20da0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
20db0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
20dc0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
20dd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
20de0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
20df0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
20e00 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
20e10 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
20e20 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
20e30 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
20e40 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
20e50 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
20e60 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
20e70 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
20e80 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
20e90 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
20ea0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
20eb0 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
20ec0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
20ed0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
20ee0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
20ef0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
20f00 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
20f10 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
20f20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
20f30 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
20f40 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
20f50 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
20f60 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
20f70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
20f80 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
20f90 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
20fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20fb0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
20fc0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
20fd0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
20fe0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
20ff0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
21000 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
21010 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
21020 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
21030 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
21040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21050 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
21060 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
21070 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
21080 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
21090 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
210a0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
210b0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
210c0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
210d0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
210e0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
210f0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
21100 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
21110 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
21120 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
21130 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
21140 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
21150 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
21160 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
21170 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
21180 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
21190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
211a0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
211b0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
211c0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
211d0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
211e0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
211f0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
21200 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
21210 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
21220 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
21230 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
21240 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
21250 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
21260 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
21270 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
21280 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
21290 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
212a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
212b0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
212c0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
212d0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
212e0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
212f0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
21300 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
21310 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
21320 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21330 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
21340 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
21350 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
21360 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
21370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
21380 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
21390 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
213a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
213b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
213c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
213d0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
213e0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
213f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21400 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
21410 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
21420 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
21430 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
21440 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
21450 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
21460 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
21470 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
21480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
21490 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
214a0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
214b0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
214c0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
214d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
214e0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
214f0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
21500 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
21510 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
21520 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
21530 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
21540 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
21550 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
21560 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
21570 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
21580 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
21590 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
215a0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
215b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
215c0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
215d0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
215e0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
215f0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
21600 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
21610 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
21620 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
21630 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
21640 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
21650 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
21660 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
21670 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
21680 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
21690 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
216a0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
216b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
216c0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
216d0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
216e0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
216f0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
21700 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
21710 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
21720 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
21730 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
21740 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
21750 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
21760 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
21770 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
21780 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
21790 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
217a0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
217b0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
217c0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
217d0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
217e0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
217f0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
21800 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
21810 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
21820 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
21830 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
21840 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
21850 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
21860 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
21870 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21880 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
21890 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
218a0 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
218b0 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
218c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
218d0 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
218e0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
218f0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
21900 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
21910 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
21920 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
21930 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
21940 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
21950 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
21960 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
21970 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
21980 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
21990 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
219a0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
219b0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
219c0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
219d0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
219e0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
219f0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
21a00 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
21a10 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
21a20 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
21a30 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
21a40 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
21a50 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
21a60 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
21a70 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
21a80 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
21a90 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
21aa0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
21ab0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
21ac0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
21ad0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
21ae0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
21af0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
21b00 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
21b10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
21b20 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
21b30 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
21b40 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
21b50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
21b60 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
21b70 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
21b80 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
21b90 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21ba0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
21bb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
21bc0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21bd0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
21be0 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
21bf0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
21c00 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
21c10 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
21c20 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
21c30 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
21c40 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21c50 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
21c60 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21c70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
21c80 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
21c90 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
21ca0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
21cb0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
21cc0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
21cd0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
21ce0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
21cf0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
21d00 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
21d10 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
21d20 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
21d30 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
21d40 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
21d50 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21d60 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
21d70 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
21d80 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
21d90 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
21da0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
21db0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
21dc0 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
21dd0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
21de0 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
21df0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
21e00 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
21e10 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
21e20 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
21e30 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
21e40 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
21e50 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
21e60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21e70 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
21e80 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
21e90 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
21ea0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
21eb0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
21ec0 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
21ed0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21ee0 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
21ef0 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
21f00 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
21f10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
21f20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
21f30 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
21f40 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
21f50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21f60 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
21f70 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
21f80 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
21f90 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
21fa0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
21fb0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
21fc0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
21fd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
21fe0 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
21ff0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
22000 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
22010 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
22020 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22030 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
22040 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
22050 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
22060 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
22070 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
22080 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
22090 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
220a0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
220b0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
220c0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
220d0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
220e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
220f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
22100 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
22110 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
22120 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
22130 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
22140 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
22150 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
22160 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
22170 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
22180 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
22190 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
221a0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
221b0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
221c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
221d0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
221e0 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
221f0 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
22200 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
22210 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
22220 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
22230 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22240 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
22250 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
22260 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
22270 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
22280 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
22290 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
222a0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
222b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
222c0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
222d0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
222e0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
222f0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
22300 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
22310 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
22320 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
22330 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
22340 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
22350 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
22360 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
22370 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
22380 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
22390 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
223a0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
223b0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
223c0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
223d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
223e0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
223f0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
22400 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
22410 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
22420 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
22430 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
22440 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
22450 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
22460 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
22470 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
22480 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
22490 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
224a0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
224b0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
224c0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
224d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
224e0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
224f0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
22500 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
22510 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
22520 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
22530 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
22540 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
22550 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
22560 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
22570 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
22580 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
22590 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
225a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
225b0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
225c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
225d0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
225e0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
225f0 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
22600 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
22610 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
22620 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
22630 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
22640 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
22650 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
22660 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
22670 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
22680 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
22690 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
226a0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
226b0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
226c0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
226d0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
226e0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
226f0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
22700 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
22710 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
22720 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22730 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
22740 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
22750 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
22760 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
22770 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
22780 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
22790 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
227a0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
227b0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
227c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
227d0 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
227e0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
227f0 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
22800 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
22810 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
22820 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
22830 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
22840 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22850 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
22860 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
22870 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
22880 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
22890 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
228a0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
228b0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
228c0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
228d0 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
228e0 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
228f0 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
22900 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
22910 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
22920 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
22930 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
22940 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
22950 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
22960 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
22970 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
22980 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
22990 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
229a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
229b0 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
229c0 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
229d0 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
229e0 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
229f0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
22a00 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
22a10 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
22a20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
22a30 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
22a40 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
22a50 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
22a60 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
22a70 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
22a80 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
22a90 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
22aa0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
22ab0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
22ac0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
22ad0 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
22ae0 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
22af0 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
22b00 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
22b10 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
22b20 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
22b30 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
22b40 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
22b50 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
22b60 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
22b70 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
22b80 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
22b90 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
22ba0 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
22bb0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
22bc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
22bd0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
22be0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
22bf0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
22c00 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
22c10 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
22c20 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
22c30 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
22c40 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
22c50 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
22c60 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
22c70 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
22c80 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
22c90 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
22ca0 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
22cb0 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
22cc0 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
22cd0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
22ce0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
22cf0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
22d00 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
22d10 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
22d20 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
22d30 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
22d40 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
22d50 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
22d60 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
22d70 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
22d80 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
22d90 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
22da0 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
22db0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
22dc0 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
22dd0 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
22de0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
22df0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
22e00 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
22e10 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
22e20 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
22e30 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
22e40 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
22e50 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
22e60 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
22e70 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
22e80 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
22e90 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
22ea0 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
22eb0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
22ec0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
22ed0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22ee0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
22ef0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
22f00 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
22f10 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22f20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
22f30 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
22f40 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
22f50 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
22f60 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
22f70 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
22f80 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
22f90 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
22fa0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
22fb0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22fc0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22fd0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
22fe0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
22ff0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
23000 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
23010 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
23020 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
23030 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
23040 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
23050 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
23060 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
23070 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
23080 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
23090 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
230a0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
230b0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
230c0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
230d0 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
230e0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
230f0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
23100 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
23110 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
23120 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
23130 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
23140 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
23150 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
23160 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
23170 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
23180 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
23190 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
231a0 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
231b0 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
231c0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
231d0 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
231e0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
231f0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
23200 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
23210 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
23220 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
23230 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
23240 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
23250 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
23260 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
23270 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
23280 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
23290 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
232a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
232b0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
232c0 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
232d0 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
232e0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
232f0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
23300 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
23310 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
23320 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
23330 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
23340 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
23350 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
23360 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
23370 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
23380 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
23390 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
233a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
233b0 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
233c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
233d0 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
233e0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
233f0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
23400 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
23410 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
23420 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
23430 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
23440 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
23450 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
23460 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
23470 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
23480 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
23490 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
234a0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
234b0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
234c0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
234d0 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
234e0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
234f0 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
23500 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
23510 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
23520 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
23530 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
23540 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
23550 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
23560 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
23570 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
23580 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
23590 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
235a0 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
235b0 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
235c0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
235d0 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
235e0 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
235f0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
23600 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
23610 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
23620 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
23630 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
23640 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
23650 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
23660 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
23670 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
23680 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
23690 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
236a0 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
236b0 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
236c0 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
236d0 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
236e0 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
236f0 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
23700 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
23710 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
23720 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
23730 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
23740 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
23750 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
23760 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
23770 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
23780 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
23790 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
237a0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
237b0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
237c0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
237d0 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
237e0 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
237f0 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
23800 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
23810 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
23820 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
23830 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
23840 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
23850 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
23860 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
23870 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
23880 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
23890 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
238a0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
238b0 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
238c0 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
238d0 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
238e0 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
238f0 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
23900 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
23910 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
23920 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
23930 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
23940 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
23950 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
23960 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
23970 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
23980 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
23990 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
239a0 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
239b0 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
239c0 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
239d0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
239e0 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
239f0 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
23a00 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
23a10 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
23a20 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
23a30 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23a40 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
23a50 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
23a60 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
23a70 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
23a80 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
23a90 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
23aa0 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
23ab0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
23ac0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
23ad0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
23ae0 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
23af0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
23b00 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
23b10 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
23b20 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
23b30 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
23b40 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
23b50 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
23b60 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
23b70 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
23b80 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
23b90 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
23ba0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
23bb0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
23bc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23bd0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
23be0 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
23bf0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
23c00 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
23c10 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
23c20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
23c30 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
23c40 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
23c50 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
23c60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
23c70 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
23c80 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
23c90 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
23ca0 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
23cb0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
23cc0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
23cd0 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
23ce0 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
23cf0 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
23d00 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
23d10 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
23d20 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
23d30 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
23d40 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
23d50 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
23d60 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
23d70 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
23d80 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
23d90 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
23da0 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
23db0 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
23dc0 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
23dd0 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
23de0 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
23df0 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
23e00 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
23e10 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
23e20 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
23e30 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
23e40 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
23e50 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
23e60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23e70 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
23e80 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
23e90 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23ea0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
23eb0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
23ec0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
23ed0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
23ee0 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
23ef0 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
23f00 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
23f10 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
23f20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
23f30 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
23f40 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
23f50 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
23f60 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
23f70 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
23f80 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
23f90 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
23fa0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
23fb0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
23fc0 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
23fd0 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
23fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
23ff0 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
24000 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
24010 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
24020 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
24030 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
24040 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
24050 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
24060 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
24070 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
24080 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
24090 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
240a0 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
240b0 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
240c0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
240d0 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
240e0 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
240f0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
24100 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
24110 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
24120 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
24130 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
24140 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
24150 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
24160 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
24170 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
24180 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
24190 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
241a0 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
241b0 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
241c0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
241d0 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
241e0 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
241f0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
24200 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
24210 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
24220 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
24230 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
24240 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
24250 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
24260 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
24270 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
24280 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
24290 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
242a0 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
242b0 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
242c0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
242d0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
242e0 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
242f0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
24300 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
24310 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
24320 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
24330 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
24340 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
24350 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
24360 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
24370 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
24380 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
24390 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
243a0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
243b0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
243c0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
243d0 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
243e0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
243f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
24400 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
24410 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
24420 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
24430 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
24440 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
24450 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
24460 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
24470 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
24480 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
24490 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
244a0 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
244b0 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
244c0 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
244d0 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
244e0 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
244f0 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
24500 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
24510 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
24520 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
24530 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
24540 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
24550 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
24560 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
24570 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
24580 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
24590 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
245a0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
245b0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
245c0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
245d0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
245e0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
245f0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
24600 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
24610 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
24620 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
24630 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
24640 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
24650 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
24660 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
24670 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
24680 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
24690 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
246a0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
246b0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
246c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
246d0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
246e0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
246f0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
24700 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
24710 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
24720 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
24730 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
24740 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
24750 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
24760 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
24770 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
24780 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
24790 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
247a0 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
247b0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
247c0 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
247d0 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
247e0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
247f0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
24800 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
24810 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
24820 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
24830 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
24840 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
24850 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
24860 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
24870 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
24880 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
24890 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
248a0 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
248b0 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
248c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
248d0 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
248e0 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
248f0 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
24900 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
24910 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
24920 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
24930 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
24940 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
24950 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
24960 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
24970 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
24980 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
24990 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
249a0 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
249b0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
249c0 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
249d0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
249e0 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
249f0 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
24a00 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
24a10 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
24a20 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
24a30 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
24a40 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
24a50 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
24a60 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
24a70 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
24a80 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
24a90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
24aa0 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
24ab0 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
24ac0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
24ad0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
24ae0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
24af0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
24b00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
24b10 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
24b20 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
24b30 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
24b40 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
24b50 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
24b60 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
24b70 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
24b80 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
24b90 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
24ba0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
24bb0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24bc0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
24bd0 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
24be0 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
24bf0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
24c00 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
24c10 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
24c20 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
24c30 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
24c40 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
24c50 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
24c60 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
24c70 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
24c80 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
24c90 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
24ca0 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
24cb0 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
24cc0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24cd0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24ce0 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
24cf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24d00 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
24d10 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
24d20 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
24d30 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
24d40 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
24d50 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
24d60 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
24d70 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
24d80 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
24d90 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
24da0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
24db0 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
24dc0 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
24dd0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
24de0 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
24df0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
24e00 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
24e10 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
24e20 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
24e30 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24e40 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
24e50 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
24e60 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
24e70 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
24e80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
24e90 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
24ea0 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
24eb0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
24ec0 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
24ed0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
24ee0 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
24ef0 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
24f00 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
24f10 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
24f20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24f30 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24f40 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
24f50 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
24f60 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e  har *zParam);.in
24f70 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
24f80 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
24f90 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
24fa0 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
24fb0 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69   bDefault);.sqli
24fc0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
24fd0 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
24fe0 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
24ff0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
25000 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
25010 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
25020 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
25030 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
25040 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
25050 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
25060 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
25070 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
25080 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
25090 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
250a0 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
250b0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
250c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
250d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
250e0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
250f0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
25100 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
25110 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
25120 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
25130 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
25140 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
25150 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
25160 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
25170 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
25180 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
25190 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
251a0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
251b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
251c0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
251d0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
251e0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
251f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
25200 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
25210 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
25220 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
25230 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
25240 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
25250 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
25260 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
25270 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
25280 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
25290 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
252a0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
252b0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
252c0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
252d0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
252e0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
252f0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
25300 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
25310 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
25320 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
25330 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
25340 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
25350 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
25360 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
25370 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
25380 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
25390 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
253a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
253b0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
253c0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
253d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
253e0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
253f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25400 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
25410 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
25420 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
25430 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
25440 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
25450 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
25460 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
25470 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
25480 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
25490 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
254a0 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
254b0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
254c0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
254d0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
254e0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
254f0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
25500 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
25510 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
25520 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
25530 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
25540 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
25550 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
25560 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
25570 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
25580 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
25590 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
255a0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
255b0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
255c0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
255d0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
255e0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
255f0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
25600 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
25610 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
25620 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
25630 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
25640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25650 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
25660 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
25670 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
25680 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
25690 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
256a0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
256b0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
256c0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
256d0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
256e0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
256f0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
25700 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
25710 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
25720 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
25730 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
25740 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
25750 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
25760 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
25770 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
25780 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
25790 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
257a0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
257b0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
257c0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
257d0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
257e0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
257f0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
25800 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
25810 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
25820 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
25830 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
25840 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
25850 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
25860 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
25870 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
25880 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
25890 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
258a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
258b0 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
258c0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
258d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
258e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
258f0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
25900 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
25910 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
25920 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
25930 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
25940 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a  tatement that.**
25950 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c   has been compil
25960 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66  ed into binary f
25970 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79  orm and is ready
25980 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
25990 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66  ..**.** Think of
259a0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
259b0 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74  ent as a separat
259c0 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72  e computer progr
259d0 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67  am.  The.** orig
259e0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73  inal SQL text is
259f0 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41   source code.  A
25a00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25a10 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69  ent object .** i
25a20 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f  s the compiled o
25a30 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c  bject code.  All
25a40 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e   SQL must be con
25a50 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a  verted into a.**
25a60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25a70 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61  ent before it ca
25a80 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  n be run..**.** 
25a90 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f  The life-cycle o
25aa0 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
25ab0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
25ac0 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20  ually goes like 
25ad0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
25ae0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
25af0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
25b00 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
25b10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
25b20 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c  pare_v2()]..** <
25b30 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
25b40 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  to [parameters] 
25b50 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
25b60 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
25b70 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
25b80 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
25b90 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
25ba0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
25bb0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
25bc0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
25bd0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
25be0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
25bf0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
25c00 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
25c10 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
25c20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
25c30 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
25c40 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
25c50 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
25c60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25c70 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74  ]..** </ol>.*/.t
25c80 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
25c90 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
25ca0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
25cb0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
25cc0 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54  me Limits.** MET
25cd0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
25ce0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
25cf0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
25d00 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
25d10 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
25d20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
25d30 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
25d40 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
25d50 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
25d60 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
25d70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25d80 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
25d90 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
25da0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
25db0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
25dc0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
25dd0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
25de0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
25df0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
25e00 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
25e10 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
25e20 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
25e30 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
25e40 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
25e50 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
25e60 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
25e70 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
25e80 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
25e90 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
25ea0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
25eb0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
25ec0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
25ed0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
25ee0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
25ef0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25f00 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
25f10 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
25f20 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
25f30 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
25f40 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
25f50 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
25f60 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
25f70 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
25f80 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
25f90 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
25fa0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
25fb0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
25fc0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
25fd0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
25fe0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
25ff0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
26000 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
26010 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
26020 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
26030 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
26040 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
26050 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
26060 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
26070 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
26080 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
26090 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
260a0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
260b0 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
260c0 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
260d0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
260e0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
260f0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
26100 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
26110 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
26120 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
26130 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
26140 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
26150 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
26160 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
26170 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
26180 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
26190 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
261a0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
261b0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
261c0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
261d0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
261e0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
261f0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
26200 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
26210 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
26220 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
26230 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
26240 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
26250 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
26260 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
26270 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
26280 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
26290 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
262a0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
262b0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
262c0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
262d0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
262e0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
262f0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
26300 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
26310 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
26320 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
26330 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
26340 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
26350 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
26360 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
26370 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
26380 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
26390 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
263a0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
263b0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
263c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
263d0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
263e0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
263f0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
26400 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
26410 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
26420 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
26430 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
26440 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
26450 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
26460 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
26470 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
26480 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
26490 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
264a0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
264b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
264c0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
264d0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
264e0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
264f0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
26500 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
26510 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
26520 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
26530 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
26540 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
26550 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
26560 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
26570 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
26580 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
26590 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
265a0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
265b0 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
265c0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
265d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
265e0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
265f0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
26600 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
26610 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
26620 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
26630 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26640 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
26650 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26660 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
26670 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
26680 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
26690 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
266a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
266b0 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
266c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
266d0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
266e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
266f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
26700 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
26710 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
26720 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26730 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
26740 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26750 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
26760 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
26770 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
26780 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
26790 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
267a0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
267b0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
267c0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
267d0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
267e0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
267f0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
26800 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
26810 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
26820 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
26830 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
26840 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
26850 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
26860 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26870 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
26880 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
26890 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
268a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
268b0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
268c0 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
268d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
268e0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
268f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26900 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26910 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
26920 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
26930 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
26940 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26950 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
26960 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
26970 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
26980 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
26990 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
269a0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
269b0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
269c0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
269d0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
269e0 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
269f0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
26a00 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
26a10 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
26a20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
26a30 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
26a40 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
26a50 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
26a60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26a70 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
26a80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26a90 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
26aa0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26ab0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26ac0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
26ad0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
26ae0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26af0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
26b00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26b10 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
26b20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26b30 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
26b40 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
26b50 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
26b60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
26b70 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
26b80 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
26b90 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
26ba0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
26bb0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
26bc0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26bd0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
26be0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
26bf0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
26c00 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
26c10 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
26c20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26c30 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
26c40 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
26c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
26c60 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
26c70 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26c80 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
26c90 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
26ca0 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
26cb0 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
26cc0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
26cd0 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
26ce0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26cf0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
26d00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26d10 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
26d20 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
26d30 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
26d40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26d50 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26d60 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
26d70 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
26d80 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
26d90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26da0 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
26db0 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
26dc0 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
26dd0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
26de0 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
26df0 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
26e00 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
26e10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
26e20 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
26e30 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
26e40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
26e50 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
26e60 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
26e70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
26e80 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
26e90 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
26ea0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
26eb0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
26ec0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
26ed0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26ee0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
26ef0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
26f00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26f10 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
26f20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
26f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26f40 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
26f50 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
26f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26f70 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
26f80 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
26f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26fa0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
26fb0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
26fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26fd0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26fe0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
26ff0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27000 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
27010 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
27020 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
27030 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
27040 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
27050 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
27060 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
27070 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
27080 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
27090 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
270a0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ler}.** METHOD: 
270b0 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54  sqlite3.** CONST
270c0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
270d0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  stmt.**.** To ex
270e0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
270f0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
27100 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
27110 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
27120 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
27130 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
27140 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
27150 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
27160 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
27170 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27180 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
27190 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
271a0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
271b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
271c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
271d0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
271e0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
271f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
27200 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
27210 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
27220 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
27230 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
27240 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
27250 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
27260 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
27270 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
27280 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
27290 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
272a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
272b0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
272c0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
272d0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
272e0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
272f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27300 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
27310 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
27320 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
27330 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ent is negative,
27340 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
27350 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
27360 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
27370 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
27380 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
27390 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20  en it is the.** 
273a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
273b0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
273c0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65   ^If nByte is ze
273d0 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70  ro, then no prep
273e0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
273f0 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a  t is generated..
27400 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  ** If the caller
27410 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20   knows that the 
27420 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
27430 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
27440 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65  d, then.** there
27450 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66   is a small perf
27460 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
27470 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20  e to passing an 
27480 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
27490 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e  that.** is the n
274a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
274b0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
274c0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
274d0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
274e0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
274f0 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
27500 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
27510 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
27520 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
27530 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
27540 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
27550 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
27560 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
27570 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
27580 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
27590 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
275a0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
275b0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
275c0 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
275d0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
275e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
275f0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
27600 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
27610 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
27620 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
27630 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
27640 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
27650 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
27660 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
27670 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
27680 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
27690 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
276a0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
276b0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
276c0 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
276d0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
276e0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
276f0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
27700 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
27710 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
27720 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
27730 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
27740 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
27750 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
27760 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
27770 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
27780 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
27790 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
277a0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
277b0 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
277c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
277d0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
277e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
277f0 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
27800 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
27810 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
27820 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27830 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
27840 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
27850 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
27860 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
27870 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
27880 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
27890 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
278a0 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
278b0 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
278c0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
278d0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
278e0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
278f0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
27900 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
27910 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27920 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
27930 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
27940 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
27950 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
27960 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
27970 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
27980 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
27990 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
279a0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
279b0 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
279c0 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
279d0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
279e0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
279f0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
27a00 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
27a10 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
27a20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
27a30 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
27a40 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
27a50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
27a60 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
27a70 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
27a80 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
27a90 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
27aa0 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20   again. As many 
27ab0 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53  as [SQLITE_MAX_S
27ac0 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20  CHEMA_RETRY].** 
27ad0 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63  retries will occ
27ae0 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  ur before sqlite
27af0 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75  3_step() gives u
27b00 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e  p and returns an
27b10 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e   error..** </li>
27b20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
27b30 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
27b40 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
27b50 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
27b60 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
27b70 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
27b80 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
27b90 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
27ba0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
27bb0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
27bc0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
27bd0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
27be0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
27bf0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
27c00 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
27c10 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
27c20 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
27c30 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
27c40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
27c50 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
27c60 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
27c70 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
27c80 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
27c90 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
27ca0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
27cb0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
27cc0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
27cd0 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
27ce0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
27cf0 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
27d00 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
27d10 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  the specific val
27d20 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72  ue bound to [par
27d30 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
27d40 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
27d50 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
27d60 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
27d70 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71   the choice of q
27d80 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20  uery plan for a 
27d90 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68  statement,.** th
27da0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
27db0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
27dc0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
27dd0 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68  d, as if there h
27de0 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63  ad been .** a sc
27df0 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20  hema change, on 
27e00 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69  the first  [sqli
27e10 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
27e20 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
27e30 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20  hange.** to the 
27e40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
27e50 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
27e60 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65  f that [paramete
27e70 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65  r]. .** ^The spe
27e80 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57  cific value of W
27e90 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72  HERE-clause [par
27ea0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e  ameter] might in
27eb0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20  fluence the .** 
27ec0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
27ed0 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61  plan if the para
27ee0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66  meter is the lef
27ef0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61  t-hand side of a
27f00 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47   [LIKE].** or [G
27f10 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72  LOB] operator or
27f20 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
27f30 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f  r is compared to
27f40 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75   an indexed colu
27f50 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53  mn.** and the [S
27f60 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41  QLITE_ENABLE_STA
27f70 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  T3] compile-time
27f80 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
27f90 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ed..** </li>.** 
27fa0 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ol>.*/.int sql
27fb0 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
27fc0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
27fd0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
27fe0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
27ff0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
28000 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28010 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
28020 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
28030 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
28040 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
28050 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
28060 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
28070 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
28080 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
28090 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
280a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
280b0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
280c0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
280d0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
280e0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
280f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28100 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
28110 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28120 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28130 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28140 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
28150 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
28160 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
28170 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28180 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28190 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
281a0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
281b0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
281c0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
281d0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
281e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
281f0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
28200 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28210 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28220 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28230 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
28240 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
28250 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
28260 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
28270 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28280 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
28290 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
282a0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
282b0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
282c0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
282d0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
282e0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
282f0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
28300 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
28310 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
28320 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
28330 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
28340 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
28350 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
28360 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
28370 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
28380 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
28390 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
283a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
283b0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
283c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
283d0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
283e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
283f0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
28400 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
28410 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
28420 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
28430 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
28440 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
28450 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
28460 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
28470 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
28480 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
28490 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
284a0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
284b0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
284c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
284d0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
284e0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
284f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
28500 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  mt.**.** ^This i
28510 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
28520 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
28530 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
28540 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
28550 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
28560 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
28570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28580 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
28590 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
285a0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
285b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
285c0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
285d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
285e0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
285f0 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
28600 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
28610 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28620 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
28630 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
28640 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
28650 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
28660 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
28670 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28680 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
28690 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
286a0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
286b0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
286c0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
286d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
286e0 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
286f0 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
28700 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
28710 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28720 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
28730 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
28740 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28750 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
28760 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
28770 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
28780 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
28790 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
287a0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
287b0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
287c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
287d0 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
287e0 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
287f0 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
28800 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
28810 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
28820 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
28830 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
28840 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
28850 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
28860 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
28870 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
28880 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
28890 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
288a0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
288b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
288c0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
288d0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
288e0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
288f0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
28900 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
28910 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
28920 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
28930 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
28940 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
28950 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
28960 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
28970 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
28980 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
28990 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
289a0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
289b0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
289c0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
289d0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
289e0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
289f0 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
28a00 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
28a10 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
28a20 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
28a30 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
28a40 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
28a50 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
28a60 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
28a70 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
28a80 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
28a90 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
28aa0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
28ab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
28ac0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
28ad0 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
28ae0 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
28af0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
28b00 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
28b10 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
28b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
28b30 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
28b40 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
28b50 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
28b60 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
28b70 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74   on disk..*/.int
28b80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28b90 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
28ba0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
28bb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
28bc0 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
28bd0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
28be0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
28bf0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28c00 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
28c10 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
28c20 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
28c30 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
28c40 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
28c50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
28c60 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
28c70 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
28c80 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
28c90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
28ca0 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
28cb0 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
28cc0 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
28cd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
28ce0 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
28cf0 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
28d00 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
28d10 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
28d20 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
28d30 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
28d40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
28d50 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
28d60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
28d70 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
28d80 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
28d90 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
28da0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
28db0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
28dc0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
28dd0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
28de0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
28df0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
28e00 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
28e10 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
28e20 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
28e30 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
28e40 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
28e50 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
28e60 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
28e70 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
28e80 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
28e90 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
28ea0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
28eb0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
28ec0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
28ed0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
28ee0 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
28ef0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
28f00 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
28f10 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
28f20 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
28f30 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
28f40 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
28f50 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
28f60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
28f70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28f80 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
28f90 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
28fa0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
28fb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28fc0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
28fd0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28fe0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
28ff0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
29000 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
29010 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
29020 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
29030 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
29040 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
29050 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
29060 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
29070 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
29080 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
29090 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
290a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
290b0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
290c0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
290d0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
290e0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
290f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
29100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29110 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
29120 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
29130 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
29140 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
29150 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
29160 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29170 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
29180 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
29190 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
291a0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
291b0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
291c0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
291d0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
291e0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
291f0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
29200 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
29210 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
29220 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
29230 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29240 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
29250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
29260 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
29270 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
29280 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
29290 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
292a0 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
292b0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
292c0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
292d0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
292e0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
292f0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
29300 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
29310 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
29320 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
29330 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
29340 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
29350 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
29360 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
29370 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
29380 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
29390 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
293a0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
293b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
293c0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
293d0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
293e0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
293f0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
29400 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
29410 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
29420 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
29430 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
29440 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
29450 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
29460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
29470 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
29480 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
29490 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
294a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
294b0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
294c0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
294d0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
294e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
294f0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
29500 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
29510 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
29520 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
29530 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
29540 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
29550 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
29560 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
29570 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
29580 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
29590 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
295a0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
295b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
295c0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
295d0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
295e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
295f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29600 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
29610 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
29620 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
29630 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
29640 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29650 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
29660 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
29670 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
29680 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
29690 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
296a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
296b0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
296c0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
296d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
296e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
296f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
29700 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
29710 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
29720 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
29730 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
29740 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29750 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
29760 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
29770 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
29780 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
29790 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
297a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
297b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
297c0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
297d0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
297e0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
297f0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
29800 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
29810 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
29820 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
29830 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
29840 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
29850 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
29860 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
29870 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
29880 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
29890 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
298a0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
298b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
298c0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
298d0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
298e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
298f0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
29900 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
29910 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
29920 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
29930 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
29940 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
29950 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
29960 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
29970 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
29980 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
29990 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
299a0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
299b0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
299c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
299d0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
299e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
299f0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
29a00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
29a10 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
29a20 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
29a30 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
29a40 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
29a50 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
29a60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
29a70 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
29a80 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
29a90 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
29aa0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
29ab0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
29ac0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
29ad0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
29ae0 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ding}.** METHOD:
29af0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
29b00 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
29b10 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
29b20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
29b30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29b40 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
29b50 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
29b60 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
29b70 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
29b80 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
29b90 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
29ba0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
29bb0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
29bc0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
29bd0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
29be0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
29bf0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
29c00 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
29c10 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
29c20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
29c30 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
29c40 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
29c50 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
29c60 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
29c70 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
29c80 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
29c90 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
29ca0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
29cb0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
29cc0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
29cd0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
29ce0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
29cf0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
29d00 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
29d10 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
29d20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
29d30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29d40 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
29d50 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
29d60 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
29d70 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
29d80 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
29d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
29da0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
29db0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
29dc0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
29dd0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
29de0 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
29df0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
29e00 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
29e10 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
29e20 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
29e30 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
29e40 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
29e50 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
29e60 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
29e70 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
29e80 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
29e90 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
29ea0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
29eb0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
29ec0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
29ed0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
29ee0 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
29ef0 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
29f00 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
29f10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29f20 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
29f30 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
29f40 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
29f50 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
29f60 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
29f70 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
29f80 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
29f90 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
29fa0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
29fb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
29fc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
29fd0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
29fe0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
29ff0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
2a000 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2a010 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
2a020 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
2a030 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2a040 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2a050 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2a060 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2a070 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2a080 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2a090 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
2a0a0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
2a0b0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a0c0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
2a0d0 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
2a0e0 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
2a0f0 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
2a100 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
2a110 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2a120 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2a130 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2a140 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2a150 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2a160 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2a170 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2a180 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2a190 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2a1a0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2a1b0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2a1c0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2a1d0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2a1e0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2a1f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2a200 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2a210 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2a220 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2a230 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2a240 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2a250 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2a260 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2a270 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2a280 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2a290 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2a2a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2a2b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2a2c0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2a2d0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2a2e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2a2f0 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2a300 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2a310 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2a320 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2a330 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2a340 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2a350 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
2a360 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2a370 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
2a380 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2a390 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2a3a0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2a3b0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2a3c0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2a3d0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2a3e0 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2a3f0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2a400 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2a410 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2a420 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2a430 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2a440 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a450 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2a460 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2a470 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2a480 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2a490 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2a4a0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2a4b0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2a4c0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2a4d0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2a4e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2a4f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2a500 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
2a510 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
2a520 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
2a530 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2a540 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2a550 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2a560 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2a570 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2a580 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2a590 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2a5a0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2a5b0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2a5c0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2a5d0 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
2a5e0 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
2a5f0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2a600 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2a610 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2a620 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2a630 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2a640 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2a650 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2a660 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2a670 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2a680 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2a690 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2a6a0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2a6b0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2a6c0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2a6d0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2a6e0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2a6f0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2a700 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2a710 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2a720 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a730 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2a740 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2a750 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2a760 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a770 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
2a780 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
2a790 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2a7a0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
2a7b0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2a7c0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
2a7d0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
2a7e0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2a7f0 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
2a800 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
2a810 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
2a820 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2a830 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2a840 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
2a850 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
2a860 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
2a870 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
2a880 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2a890 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
2a8a0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2a8b0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
2a8c0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
2a8d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
2a8e0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2a8f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a900 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2a910 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2a920 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2a930 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2a940 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2a950 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2a960 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2a970 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2a980 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2a990 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2a9a0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2a9b0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2a9c0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2a9d0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2a9e0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2a9f0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2aa00 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2aa10 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2aa20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2aa30 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2aa40 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2aa50 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2aa60 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2aa70 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2aa80 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2aa90 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2aaa0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
2aab0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2aac0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2aad0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
2aae0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2aaf0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
2ab00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ab10 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
2ab20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
2ab30 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
2ab40 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2ab50 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
2ab60 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
2ab70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ab80 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
2ab90 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
2aba0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2abb0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
2abc0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
2abd0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
2abe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2abf0 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
2ac00 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
2ac10 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
2ac20 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2ac30 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
2ac40 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
2ac50 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
2ac60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
2ac70 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
2ac80 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
2ac90 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
2aca0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
2acb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2acc0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
2acd0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2ace0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2acf0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
2ad00 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
2ad10 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
2ad20 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
2ad30 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
2ad40 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
2ad50 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
2ad60 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
2ad70 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
2ad80 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2ad90 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2ada0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
2adb0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
2adc0 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
2add0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
2ade0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
2adf0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
2ae00 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
2ae10 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
2ae20 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
2ae30 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
2ae40 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2ae50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ae60 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
2ae70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ae80 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2ae90 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2aea0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2aeb0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
2aec0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2aed0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2aee0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2aef0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2af00 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2af10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2af20 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2af30 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2af40 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
2af50 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2af60 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2af70 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2af80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
2af90 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2afa0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2afb0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2afc0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
2afd0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
2afe0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2aff0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
2b000 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2b010 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
2b020 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
2b030 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
2b040 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2b050 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2b060 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
2b070 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
2b080 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2b0a0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
2b0b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b0c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2b0d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b0e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b0f0 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
2b100 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2b110 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2b120 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2b130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b140 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2b150 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
2b160 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73  encoding);.int s
2b170 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2b180 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b190 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2b1a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2b1b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2b1c0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2b1d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2b1e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b1f0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
2b200 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b210 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
2b220 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2b230 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2b240 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2b250 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b260 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
2b270 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2b280 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2b290 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2b2a0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2b2b0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2b2c0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2b2d0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2b2e0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2b2f0 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2b300 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2b310 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2b320 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2b330 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2b340 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2b350 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b360 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2b370 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2b380 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2b390 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2b3a0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2b3b0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2b3c0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2b3d0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2b3e0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2b3f0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2b400 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2b410 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2b420 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
2b430 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
2b440 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
2b450 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
2b460 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
2b470 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
2b480 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
2b490 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b4a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b4b0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b4c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b4d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2b4e0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2b4f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b500 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2b510 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2b520 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b530 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2b540 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b550 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
2b560 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
2b570 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b580 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2b590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b5a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2b5b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b5c0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2b5d0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2b5e0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2b5f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b600 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2b610 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2b620 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2b630 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2b640 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2b650 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2b660 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2b670 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2b680 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2b690 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2b6a0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2b6b0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2b6c0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2b6d0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2b6e0 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2b6f0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2b700 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2b710 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2b720 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2b730 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2b740 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2b750 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2b760 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2b770 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2b780 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2b790 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2b7a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2b7b0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2b7c0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2b7d0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2b7e0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2b7f0 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2b800 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2b810 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2b820 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2b830 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2b840 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2b850 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2b860 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2b870 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2b880 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2b890 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2b8a0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2b8b0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2b8c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b8d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b8e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b8f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b900 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b910 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b920 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b930 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2b940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b950 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b960 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2b970 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b980 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2b990 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2b9a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b9b0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2b9c0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2b9d0 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f  en Name.** METHO
2b9e0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2b9f0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2ba00 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
2ba10 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
2ba20 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
2ba30 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
2ba40 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
2ba50 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
2ba60 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
2ba70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2ba80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2ba90 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
2baa0 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
2bab0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
2bac0 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
2bad0 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
2bae0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
2baf0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
2bb00 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
2bb10 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
2bb20 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
2bb30 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
2bb40 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
2bb50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bb60 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2bb70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2bb80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2bb90 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2bba0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2bbb0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2bbc0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2bbd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bbe0 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  r_name()]..*/.in
2bbf0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2bc00 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2bc10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2bc20 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2bc30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bc40 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2bc50 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2bc60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2bc70 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2bc80 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  _stmt.**.** ^Con
2bc90 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
2bca0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
2bcb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2bcc0 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
2bcd0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2bce0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
2bcf0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
2bd00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bd10 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
2bd20 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
2bd30 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
2bd40 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
2bd50 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
2bd60 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2bd70 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2bd80 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2bd90 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2bda0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2bdb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2bdc0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2bdd0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2bde0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2bdf0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2be00 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2be10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2be20 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2be30 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2be40 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2be50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2be60 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2be70 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2be80 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2be90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2bea0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2beb0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2bec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2bed0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2bee0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2bef0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2bf00 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2bf10 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2bf20 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2bf30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2bf40 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2bf50 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
2bf60 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
2bf70 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
2bf80 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
2bf90 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2bfa0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
2bfb0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2bfc0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2bfd0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2bfe0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2bff0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
2c000 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
2c010 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2c020 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c030 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2c040 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
2c050 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2c060 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2c070 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
2c080 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
2c090 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2c0a0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2c0b0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
2c0c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2c0d0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
2c0e0 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
2c0f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
2c100 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
2c110 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2c120 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
2c130 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
2c140 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2c150 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
2c160 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
2c170 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c180 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2c190 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2c1a0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2c1b0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2c1c0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2c1d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2c1e0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2c1f0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2c200 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
2c210 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c220 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
2c230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2c240 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
2c250 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2c260 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
2c270 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
2c280 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
2c290 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
2c2a0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
2c2b0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
2c2c0 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
2c2d0 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
2c2e0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
2c2f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2c300 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2c310 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
2c320 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
2c330 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
2c340 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
2c350 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
2c360 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
2c370 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
2c380 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
2c390 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
2c3a0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
2c3b0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
2c3c0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
2c3d0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
2c3e0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
2c3f0 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
2c400 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c410 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c420 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
2c430 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2c440 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2c450 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c460 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2c470 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2c480 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2c490 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2c4a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2c4b0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2c4c0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2c4d0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2c4e0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2c4f0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2c500 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2c510 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2c520 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2c530 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2c540 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2c550 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2c560 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2c570 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2c580 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2c590 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2c5a0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2c5b0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2c5c0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2c5d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2c5e0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2c5f0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2c600 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c610 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2c620 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2c630 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2c640 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2c650 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2c660 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2c670 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2c680 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c690 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2c6a0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2c6b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c6c0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2c6d0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2c6e0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2c6f0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2c700 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2c710 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2c720 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2c730 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2c740 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2c750 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2c760 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2c770 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2c780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2c790 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2c7a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2c7b0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2c7c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2c7d0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2c7e0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2c7f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2c800 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2c810 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2c820 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2c830 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2c840 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2c850 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2c860 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2c870 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2c880 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2c890 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2c8a0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2c8b0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2c8c0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2c8d0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2c8e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2c8f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2c900 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2c910 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2c920 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2c930 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2c940 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2c950 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2c960 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2c970 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2c980 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2c990 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2c9a0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2c9b0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2c9c0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2c9d0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2c9e0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2c9f0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2ca00 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2ca10 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2ca20 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2ca30 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2ca40 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2ca50 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2ca60 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2ca70 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2ca80 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2ca90 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2caa0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2cab0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2cac0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2cad0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2cae0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2caf0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2cb00 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2cb10 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2cb20 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2cb30 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2cb40 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2cb50 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2cb60 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2cb70 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2cb80 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2cb90 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2cba0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2cbb0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2cbc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2cbd0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2cbe0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2cbf0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2cc00 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2cc10 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2cc20 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2cc30 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2cc40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2cc50 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2cc60 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2cc70 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2cc80 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2cc90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2cca0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2ccb0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2ccc0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2ccd0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2cce0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2ccf0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2cd00 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2cd10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2cd20 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2cd30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2cd40 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2cd50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2cd60 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2cd70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2cd80 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2cd90 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2cda0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2cdb0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2cdc0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2cdd0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2cde0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2cdf0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2ce00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2ce10 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2ce20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ce30 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2ce40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2ce50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ce60 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2ce70 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2ce80 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2ce90 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2cea0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2ceb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2cec0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ced0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2cee0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2cef0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2cf00 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2cf10 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2cf20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2cf30 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2cf40 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2cf50 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2cf60 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2cf70 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2cf80 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2cf90 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2cfa0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2cfb0 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2cfc0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2cfd0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2cfe0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2cff0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2d000 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2d010 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2d020 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2d030 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2d040 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2d050 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2d060 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2d070 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2d080 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2d090 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2d0a0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2d0b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2d0c0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2d0d0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2d0e0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2d0f0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2d100 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2d110 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2d120 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2d130 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2d140 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2d150 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2d160 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2d170 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2d180 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2d190 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2d1a0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2d1b0 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2d1c0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2d1d0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2d1e0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2d1f0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2d200 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2d210 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2d220 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2d230 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2d240 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2d250 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2d260 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2d270 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2d280 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2d290 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2d2a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2d2b0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2d2c0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2d2d0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2d2e0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2d2f0 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
2d300 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d310 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2d320 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2d330 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2d340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2d350 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2d360 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2d370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2d380 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2d390 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2d3a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d3b0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2d3c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d3d0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2d3e0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2d3f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2d400 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2d410 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2d420 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2d430 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2d440 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2d450 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2d460 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d470 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2d480 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2d490 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2d4a0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2d4b0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2d4c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2d4d0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2d4e0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2d4f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2d500 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2d510 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2d520 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2d530 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2d540 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2d550 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2d560 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d570 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2d580 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2d590 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2d5a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2d5b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2d5c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2d5d0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2d5e0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2d5f0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2d600 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2d610 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2d620 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2d630 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2d640 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2d650 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2d660 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2d670 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2d680 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2d690 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2d6a0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2d6b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2d6c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2d6d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2d6e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2d6f0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2d700 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2d710 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2d720 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2d730 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2d740 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2d750 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2d760 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2d770 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2d780 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2d790 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2d7a0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2d7b0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2d7c0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2d7d0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2d7e0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2d7f0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2d800 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2d810 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2d820 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2d830 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2d840 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2d850 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2d860 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2d870 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2d880 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2d890 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2d8a0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2d8b0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2d8c0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2d8d0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2d8e0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2d8f0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2d900 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2d910 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2d920 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2d930 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2d940 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2d950 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2d960 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2d970 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2d980 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2d990 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2d9a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2d9b0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2d9c0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2d9d0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2d9e0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2d9f0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2da00 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2da10 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2da20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2da30 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2da40 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2da50 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2da60 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2da70 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2da80 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2da90 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2daa0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2dab0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2dac0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2dad0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2dae0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2daf0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2db00 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2db10 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2db20 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2db30 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2db40 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2db50 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2db60 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2db70 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2db80 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2db90 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2dba0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2dbb0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2dbc0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2dbd0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2dbe0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2dbf0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2dc00 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2dc10 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2dc20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2dc30 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2dc40 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2dc50 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2dc60 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2dc70 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2dc80 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2dc90 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2dca0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2dcb0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2dcc0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2dcd0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2dce0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2dcf0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2dd00 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2dd10 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2dd20 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2dd30 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2dd40 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2dd50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2dd60 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2dd70 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2dd80 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2dd90 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2dda0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2ddb0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2ddc0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2ddd0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2dde0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2ddf0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2de00 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2de10 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2de20 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2de30 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2de40 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2de50 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2de60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2de70 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2de80 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2de90 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2dea0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2deb0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2dec0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2ded0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2dee0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2def0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2df00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2df10 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2df20 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2df30 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2df40 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2df50 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2df60 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2df70 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2df80 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2df90 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2dfa0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2dfb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2dfc0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2dfd0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2dfe0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2dff0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2e000 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2e010 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2e020 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2e030 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2e040 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2e050 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2e060 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2e070 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2e080 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2e090 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2e0a0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2e0b0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2e0c0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2e0d0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2e0e0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2e0f0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2e100 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2e110 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2e120 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2e130 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2e140 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2e150 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2e160 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2e170 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2e180 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2e190 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2e1a0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2e1b0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2e1c0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2e1d0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2e1e0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2e1f0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2e200 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2e210 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2e220 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2e230 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2e240 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2e250 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2e260 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2e270 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2e280 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2e290 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2e2a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e2b0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2e2c0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2e2d0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2e2e0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2e2f0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2e300 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2e310 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2e320 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2e330 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2e340 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2e350 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2e360 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2e370 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2e380 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2e390 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2e3a0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2e3b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2e3c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2e3d0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2e3e0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2e3f0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2e400 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2e410 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2e420 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2e430 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2e440 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2e450 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2e460 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2e470 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2e480 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2e490 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2e4a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2e4b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e4c0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2e4d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2e4e0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2e4f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2e500 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
2e510 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2e520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e530 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2e540 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2e550 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e560 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2e570 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2e580 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2e590 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2e5a0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2e5b0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2e5c0 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2e5d0 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2e5e0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2e5f0 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2e600 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2e610 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2e620 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2e630 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2e640 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2e650 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2e660 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2e670 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e680 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2e690 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2e6a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e6b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2e6c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2e6d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2e6e0 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2e6f0 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2e700 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2e710 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2e720 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2e730 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e740 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2e750 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2e760 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2e770 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2e780 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2e790 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2e7a0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2e7b0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2e7c0 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2e7d0 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2e7e0 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2e7f0 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2e800 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2e810 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2e820 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2e830 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2e840 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2e850 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2e860 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2e870 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2e880 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2e890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e8a0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2e8b0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2e8c0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2e8d0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2e8e0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2e8f0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2e900 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2e910 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2e920 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2e930 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2e940 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2e950 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2e960 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2e970 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2e980 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2e990 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2e9a0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2e9b0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2e9c0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2e9d0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2e9e0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2e9f0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2ea00 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2ea10 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2ea20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2ea30 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2ea40 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2ea50 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2ea60 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2ea70 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2ea80 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2ea90 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2eaa0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2eab0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2eac0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2ead0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2eae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2eaf0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2eb00 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2eb10 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2eb20 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2eb30 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2eb40 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2eb50 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2eb60 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2eb70 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2eb80 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2eb90 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2eba0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2ebb0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2ebc0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2ebd0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2ebe0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
2ebf0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ec00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ec10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2ec20 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2ec30 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2ec40 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2ec50 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2ec60 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2ec70 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2ec80 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2ec90 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2eca0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ecb0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2ecc0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2ecd0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2ece0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2ecf0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2ed00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ed10 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2ed20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2ed30 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2ed40 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2ed50 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2ed60 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2ed70 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2ed80 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2ed90 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2eda0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2edb0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2edc0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2edd0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2ede0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2edf0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2ee00 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2ee10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2ee20 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2ee30 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2ee40 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2ee50 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2ee60 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2ee70 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2ee80 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2ee90 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2eea0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2eeb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2eec0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2eed0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2eee0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2eef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2ef00 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2ef10 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2ef20 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2ef30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2ef40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2ef50 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2ef60 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2ef70 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2ef80 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2ef90 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2efa0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2efb0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2efc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2efd0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2efe0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2eff0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2f000 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2f010 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2f020 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2f030 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2f040 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f050 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2f060 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2f070 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2f080 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2f090 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2f0a0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2f0b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2f0c0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2f0d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2f0e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2f0f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f100 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2f110 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2f120 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2f130 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2f140 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2f150 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2f160 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2f170 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2f180 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2f190 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2f1a0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2f1b0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2f1c0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2f1d0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2f1e0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2f1f0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2f200 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2f210 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2f220 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2f230 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2f240 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2f250 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2f260 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2f270 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2f280 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2f290 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2f2a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f2b0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2f2c0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2f2d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2f2e0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2f2f0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2f300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f310 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2f320 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2f330 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2f340 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2f350 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2f360 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2f370 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f380 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2f390 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f3a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2f3b0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2f3c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2f3d0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2f3e0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2f3f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f400 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2f410 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2f420 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2f430 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2f440 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2f450 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2f460 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2f470 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f480 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2f490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2f4a0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2f4b0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2f4c0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2f4d0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2f4e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f4f0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2f500 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2f510 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2f520 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2f530 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2f540 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2f550 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f560 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2f570 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2f580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f590 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2f5a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2f5b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f5c0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2f5d0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2f5e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f5f0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2f600 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2f610 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2f620 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2f630 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2f640 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2f650 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f660 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2f670 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2f680 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2f690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f6a0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2f6b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2f6c0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2f6d0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2f6e0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
2f6f0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2f700 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f710 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2f720 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f730 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2f740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f750 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
2f760 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
2f770 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2f780 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2f790 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2f7a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2f7b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2f7c0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
2f7d0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2f7e0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
2f7f0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
2f800 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
2f810 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
2f820 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2f830 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f840 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2f850 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f860 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
2f870 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
2f880 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
2f890 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2f8a0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
2f8b0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
2f8c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f8d0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
2f8e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f8f0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
2f900 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
2f910 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
2f920 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
2f930 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
2f940 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
2f950 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
2f960 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2f970 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
2f980 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
2f990 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
2f9a0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2f9b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2f9c0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2f9d0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2f9e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f9f0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
2fa00 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
2fa10 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
2fa20 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2fa30 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2fa40 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
2fa50 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
2fa60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2fa70 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2fa80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2fa90 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2faa0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2fab0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2fac0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2fad0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2fae0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2faf0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2fb00 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2fb10 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2fb20 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2fb30 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2fb40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fb50 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2fb60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2fb70 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
2fb80 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
2fb90 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
2fba0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2fbb0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2fbc0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2fbd0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2fbe0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2fbf0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2fc00 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2fc10 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2fc20 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2fc30 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2fc40 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2fc50 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2fc60 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2fc70 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2fc80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2fc90 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2fca0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2fcb0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2fcc0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2fcd0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2fce0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2fcf0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2fd00 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2fd10 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2fd20 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2fd30 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2fd40 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2fd50 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2fd60 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2fd70 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2fd80 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2fd90 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2fda0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2fdb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2fdc0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2fdd0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2fde0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2fdf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2fe00 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2fe10 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2fe20 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2fe30 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2fe40 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2fe50 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2fe60 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2fe70 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2fe80 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2fe90 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2fea0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2feb0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2fec0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2fed0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2fee0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2fef0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2ff00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2ff10 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2ff20 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2ff30 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2ff40 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2ff50 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2ff60 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2ff70 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2ff80 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2ff90 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2ffa0 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
2ffb0 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
2ffc0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2ffd0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2ffe0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2fff0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
30000 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
30010 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
30020 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
30030 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
30040 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
30050 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
30060 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
30070 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
30080 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
30090 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
300a0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
300b0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
300c0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
300d0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
300e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
300f0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
30100 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
30110 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
30120 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
30130 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
30140 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
30150 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
30160 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
30170 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
30180 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
30190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
301a0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
301b0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
301c0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
301d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
301e0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
301f0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
30200 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
30210 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
30220 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
30230 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
30240 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
30250 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
30260 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30270 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
30280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30290 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
302a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
302b0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
302c0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
302d0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
302e0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
302f0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
30300 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
30310 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
30320 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
30330 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
30340 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
30350 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
30360 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30370 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
30380 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
30390 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
303a0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
303b0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
303c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
303d0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
303e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
303f0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
30400 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30410 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
30420 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
30430 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
30440 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
30450 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
30460 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
30470 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
30480 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
30490 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
304a0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
304b0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
304c0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
304d0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
304e0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
304f0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
30500 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
30510 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
30520 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
30530 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
30540 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
30550 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
30560 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
30570 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
30580 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
30590 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
305a0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
305b0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
305c0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
305d0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
305e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
305f0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
30600 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
30610 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
30620 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
30630 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
30640 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
30650 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
30660 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
30670 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30680 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
30690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
306a0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
306b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
306c0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
306d0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
306e0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
306f0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
30700 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30710 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
30720 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
30730 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
30740 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
30750 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
30760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30770 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
30780 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30790 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
307a0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
307b0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
307c0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
307d0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
307e0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
307f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30800 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
30810 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
30820 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
30830 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
30840 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30850 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
30860 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
30870 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
30880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30890 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
308a0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
308b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
308c0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
308d0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
308e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
308f0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
30900 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
30910 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
30920 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
30930 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
30940 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
30950 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
30960 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
30970 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
30980 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
30990 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
309a0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
309b0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
309c0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
309d0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
309e0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
309f0 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
30a00 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
30a10 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
30a20 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
30a30 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
30a40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30a50 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
30a60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
30a70 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
30a80 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
30a90 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
30aa0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
30ab0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
30ac0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
30ad0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
30ae0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
30af0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
30b00 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
30b10 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
30b20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
30b30 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
30b40 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
30b50 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
30b60 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
30b70 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
30b80 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
30b90 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
30ba0 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
30bb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30bc0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
30bd0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
30be0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
30bf0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
30c00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30c10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
30c20 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
30c30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30c40 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
30c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
30c60 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
30c70 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
30c80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
30c90 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
30ca0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
30cb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
30cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
30cd0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30ce0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
30cf0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
30d00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30d10 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
30d20 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
30d30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30d40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30d50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30d60 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
30d70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
30d80 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
30d90 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
30da0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
30db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
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 0a 2f 2a 0a 2a  int iCol);../*.*
30de0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
30df0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
30e00 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
30e10 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
30e20 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30e30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
30e40 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
30e50 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
30e60 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
30e70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
30e80 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
30e90 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
30ea0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
30eb0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
30ec0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
30ed0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30ee0 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
30ef0 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
30f00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
30f10 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
30f20 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
30f30 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
30f40 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
30f50 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
30f60 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
30f70 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
30f80 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
30f90 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
30fa0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
30fb0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
30fc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
30fd0 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
30fe0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
30ff0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
31000 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
31010 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
31020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
31030 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
31040 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
31050 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
31060 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
31070 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
31080 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
31090 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
310a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
310b0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
310c0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
310d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
310e0 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
310f0 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
31100 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
31110 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
31120 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
31130 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
31140 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
31150 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
31160 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
31170 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31180 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
31190 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
311a0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
311b0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
311c0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
311d0 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
311e0 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
311f0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
31200 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
31210 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
31220 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
31230 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
31240 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
31250 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
31260 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
31270 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
31280 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
31290 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
312a0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
312b0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
312c0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
312d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
312e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
312f0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
31300 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
31310 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
31320 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31330 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
31340 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
31350 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
31360 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
31370 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
31380 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
31390 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
313a0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
313b0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
313c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
313d0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
313e0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
313f0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
31400 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
31410 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
31420 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
31430 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
31440 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
31450 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
31460 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
31470 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
31480 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
31490 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
314a0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
314b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
314c0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
314d0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
314e0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
314f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
31500 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
31510 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
31520 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
31530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31540 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
31550 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
31560 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
31570 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
31580 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
31590 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
315a0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
315b0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
315c0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
315d0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
315e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
315f0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
31600 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
31610 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
31620 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
31630 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
31640 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
31650 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
31660 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
31670 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
31680 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
31690 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
316a0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
316b0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
316c0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
316d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
316e0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
316f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31700 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
31710 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
31720 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
31730 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31740 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
31750 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
31760 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
31770 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
31780 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
31790 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
317a0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
317b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
317c0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
317d0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
317e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
317f0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
31800 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
31810 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
31820 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
31830 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
31840 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
31850 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
31860 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
31870 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
31880 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
31890 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
318a0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
318b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
318c0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
318d0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
318e0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
318f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
31900 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
31910 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
31920 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
31930 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
31940 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
31950 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
31960 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
31970 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
31980 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
31990 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
319a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
319b0 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
319c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
319d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
319e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
319f0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
31a00 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
31a10 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
31a20 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
31a30 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
31a40 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
31a50 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
31a60 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
31a70 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31a80 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
31a90 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
31aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31ab0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
31ac0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
31ad0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
31ae0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
31af0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
31b00 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
31b10 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
31b20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
31b30 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
31b40 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
31b50 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
31b60 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
31b70 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
31b80 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
31b90 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
31ba0 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
31bb0 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
31bc0 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
31bd0 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
31be0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
31bf0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
31c00 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
31c10 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
31c20 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
31c30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
31c40 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
31c50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
31c60 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
31c70 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
31c80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
31c90 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
31ca0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
31cb0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
31cc0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
31cd0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
31ce0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
31cf0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
31d00 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
31d10 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
31d20 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
31d30 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
31d40 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
31d50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
31d60 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
31d70 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
31d80 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
31d90 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
31da0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
31db0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
31dc0 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
31dd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
31de0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
31df0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
31e00 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
31e10 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
31e20 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
31e30 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
31e40 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
31e50 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
31e60 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
31e70 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
31e80 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
31e90 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
31ea0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
31eb0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
31ec0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
31ed0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
31ee0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
31ef0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
31f00 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
31f10 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
31f20 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
31f30 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
31f40 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
31f50 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
31f60 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31f70 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
31f80 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
31f90 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
31fa0 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
31fb0 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
31fc0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
31fd0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
31fe0 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
31ff0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
32000 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
32010 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
32020 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
32030 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
32040 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
32050 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32060 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
32070 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
32080 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
32090 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
320a0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
320b0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
320c0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
320d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
320e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
320f0 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
32100 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
32110 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
32120 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
32130 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
32140 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
32150 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
32160 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
32170 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
32180 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
32190 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
321a0 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
321b0 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
321c0 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
321d0 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
321e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
321f0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
32200 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
32210 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
32220 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
32230 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
32240 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
32250 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
32260 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
32270 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
32280 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
32290 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
322a0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
322b0 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
322c0 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
322d0 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
322e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
322f0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
32300 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
32310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32320 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
32330 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
32340 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
32350 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
32360 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
32370 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
32380 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
32390 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
323a0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
323b0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
323c0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
323d0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
323e0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
323f0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
32400 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32410 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
32420 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32430 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32440 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
32450 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
32460 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
32470 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
32480 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
32490 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
324a0 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
324b0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
324c0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
324d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
324e0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
324f0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
32500 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
32510 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
32520 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
32530 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
32540 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
32550 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
32560 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
32570 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
32580 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
32590 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
325a0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
325b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
325c0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
325d0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
325e0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
325f0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
32600 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
32610 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
32620 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
32630 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
32640 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
32650 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
32660 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
32670 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
32680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32690 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
326a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
326b0 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
326c0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
326d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
326e0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
326f0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
32700 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
32710 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
32720 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
32730 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
32740 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
32750 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
32760 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
32770 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32780 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
32790 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
327a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
327b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
327c0 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
327d0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
327e0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
327f0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
32800 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
32810 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
32820 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
32830 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
32840 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
32850 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
32860 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
32870 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
32880 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
32890 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
328a0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
328b0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
328c0 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
328d0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
328e0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
328f0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
32900 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32910 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
32920 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
32930 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
32940 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
32950 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
32960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32970 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
32980 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
32990 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
329a0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
329b0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
329c0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
329d0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
329e0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
329f0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
32a00 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
32a10 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
32a20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
32a30 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
32a40 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
32a50 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
32a60 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
32a70 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
32a80 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
32a90 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
32aa0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
32ab0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
32ac0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
32ad0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
32ae0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
32af0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
32b00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32b10 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
32b20 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
32b30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32b40 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
32b50 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
32b60 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
32b70 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
32b80 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
32b90 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
32ba0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
32bb0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
32bc0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
32bd0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
32be0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
32bf0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
32c00 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
32c10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32c20 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
32c30 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
32c40 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
32c50 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
32c60 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32c70 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
32c80 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
32c90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32ca0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32cb0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32cc0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
32cd0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32ce0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32cf0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
32d00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
32d10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32d20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32d30 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32d40 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
32d50 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
32d60 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
32d70 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
32d80 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
32d90 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
32da0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32db0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32dc0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
32dd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32de0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32df0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32e00 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
32e10 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
32e20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32e30 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
32e40 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
32e50 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
32e60 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32e70 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32e80 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
32e90 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
32ea0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32eb0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32ec0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32ed0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
32ee0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32ef0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
32f00 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
32f10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32f20 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
32f30 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
32f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32f50 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
32f60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32f70 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
32f80 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
32f90 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
32fa0 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
32fb0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
32fc0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
32fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32fe0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
32ff0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
33000 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
33010 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
33020 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
33030 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
33040 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
33050 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
33060 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
33070 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
33080 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33090 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
330a0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
330b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
330c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
330d0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
330e0 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
330f0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
33100 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
33110 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
33120 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33130 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
33140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
33150 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
33160 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
33170 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
33180 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
33190 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
331a0 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
331b0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
331c0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
331d0 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
331e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
331f0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
33200 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
33210 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33220 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33230 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
33240 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
33250 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
33260 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
33270 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
33280 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
33290 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
332a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
332b0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
332c0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
332d0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
332e0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
332f0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
33300 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
33310 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
33320 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
33330 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
33340 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
33350 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
33360 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
33370 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
33380 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
33390 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
333a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
333b0 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
333c0 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
333d0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
333e0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
333f0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
33400 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
33410 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
33420 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33430 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
33440 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
33450 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
33460 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
33470 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
33480 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
33490 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
334a0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
334b0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
334c0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
334d0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
334e0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
334f0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
33500 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
33510 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
33520 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
33530 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
33540 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
33550 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
33560 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
33570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33580 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
33590 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
335a0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
335b0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
335c0 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
335d0 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
335e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
335f0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
33600 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
33610 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
33620 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
33630 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
33640 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
33650 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
33660 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
33670 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
33680 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a   aggregate.  .**
33690 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
336a0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
336b0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
336c0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
336d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
336e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
336f0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
33700 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33710 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
33720 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
33730 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
33740 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
33750 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
33760 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
33770 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
33780 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
33790 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
337a0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
337b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
337c0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
337d0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
337e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
337f0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
33800 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
33810 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
33820 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
33830 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
33840 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
33850 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
33860 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
33870 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
33880 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
33890 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
338a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
338b0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
338c0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
338d0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
338e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
338f0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
33900 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
33910 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
33920 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
33930 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
33940 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
33950 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
33960 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
33970 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
33980 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
33990 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
339a0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
339b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
339c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
339d0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
339e0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
339f0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
33a00 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
33a10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33a20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
33a30 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
33a40 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
33a50 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
33a60 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
33a70 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
33a80 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
33a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33aa0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
33ab0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
33ac0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
33ad0 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
33ae0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
33af0 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
33b00 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
33b10 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
33b20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
33b30 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
33b40 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
33b50 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
33b60 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
33b70 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
33b80 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
33b90 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
33ba0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
33bb0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
33bc0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
33bd0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
33be0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
33bf0 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
33c00 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
33c10 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
33c20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
33c30 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
33c40 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
33c50 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
33c60 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
33c70 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
33c80 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
33c90 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
33ca0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
33cb0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
33cc0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
33cd0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
33ce0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
33cf0 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
33d00 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
33d10 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
33d20 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
33d30 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
33d40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
33d50 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
33d60 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
33d70 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
33d80 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
33d90 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
33da0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
33db0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
33dc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
33dd0 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
33de0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
33df0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33e00 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
33e10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33e20 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
33e30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
33e40 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
33e50 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
33e60 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
33e70 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
33e80 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
33e90 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
33ea0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
33eb0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
33ec0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
33ed0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
33ee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33ef0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
33f00 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
33f10 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
33f20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
33f30 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
33f40 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
33f50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
33f70 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
33f80 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
33f90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
33fa0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
33fb0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
33fc0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
33fd0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
33fe0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
33ff0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
34000 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34020 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
34030 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34040 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
34050 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
34060 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
34070 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
34080 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
34090 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
340a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
340b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
340c0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
340d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
340e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
340f0 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75  : Finding The Su
34100 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c  btype Of SQL Val
34110 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
34120 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
34130 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
34140 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20  alue_subtype(V) 
34150 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
34160 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
34170 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74  .** an [applicat
34180 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
34190 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65  function] argume
341a0 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79  nt V.  The subty
341b0 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  pe.** informatio
341c0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
341d0 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20   pass a limited 
341e0 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78  amount of contex
341f0 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51  t from.** one SQ
34200 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e  L function to an
34210 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20  other.  Use the 
34220 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34230 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f  subtype()].** ro
34240 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65  utine to set the
34250 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65   subtype for the
34260 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
34270 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
34280 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
34290 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73  akes no use of s
342a0 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20  ubtype itself.  
342b0 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73  It merely passes
342c0 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   the subtype.** 
342d0 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20  from the result 
342e0 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74  of one [applicat
342f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
34300 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74  function] into t
34310 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61  he.** input of a
34320 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67  nother..*/.unsig
34330 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  ned int sqlite3_
34340 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71  value_subtype(sq
34350 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
34360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34370 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
34380 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
34390 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
343a0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
343b0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
343c0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
343d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
343e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
343f0 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
34400 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
34410 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
34420 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
34430 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
34440 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
34450 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34460 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
34470 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
34480 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34490 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
344a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
344b0 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
344c0 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
344d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
344e0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
344f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
34500 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
34510 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
34520 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34530 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
34540 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
34550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
34560 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61  ()].  ^If V is a
34570 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
34580 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61   then sqlite3_va
34590 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61  lue_free(V) is a
345a0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
345b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
345c0 49 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f  IMENTAL sqlite3_
345d0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76  value *sqlite3_v
345e0 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73  alue_dup(const s
345f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34600 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
34610 54 41 4c 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TAL void sqlite3
34620 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69  _value_free(sqli
34630 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
34640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
34650 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
34660 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
34670 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
34680 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
34690 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
346a0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
346b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
346c0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
346d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
346e0 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
346f0 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
34700 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
34710 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
34720 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34730 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
34740 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
34750 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
34760 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
34770 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
34780 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
34790 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
347a0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
347b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
347c0 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
347d0 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
347e0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
347f0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
34800 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34810 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
34820 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
34830 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
34840 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
34850 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
34860 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
34870 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
34880 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
34890 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
348a0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
348b0 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
348c0 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
348d0 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
348e0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
348f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
34900 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
34910 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
34920 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
34930 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
34940 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
34950 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
34960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34970 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
34980 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
34990 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
349a0 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
349b0 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
349c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
349d0 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
349e0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
349f0 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
34a00 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
34a10 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
34a20 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34a30 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
34a40 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
34a50 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
34a60 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
34a70 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
34a80 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
34a90 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
34aa0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
34ab0 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
34ac0 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
34ad0 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
34ae0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
34af0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34b00 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
34b10 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
34b20 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
34b30 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
34b40 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
34b50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
34b60 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
34b70 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
34b80 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
34b90 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
34ba0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
34bb0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
34bc0 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
34bd0 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
34be0 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
34bf0 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
34c00 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
34c10 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
34c20 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
34c30 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
34c40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
34c50 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
34c60 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
34c70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
34c80 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
34c90 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
34ca0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
34cb0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
34cc0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
34cd0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
34ce0 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
34cf0 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
34d00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
34d10 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
34d20 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
34d30 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
34d40 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
34d50 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
34d60 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
34d70 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
34d80 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
34d90 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
34da0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
34db0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
34dc0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
34dd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34de0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
34df0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34e00 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
34e10 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
34e20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
34e30 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
34e40 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
34e50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
34e60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34e70 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
34e80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
34e90 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
34ea0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
34eb0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
34ec0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34ed0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
34ee0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34ef0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
34f00 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
34f10 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
34f20 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
34f30 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
34f40 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
34f50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34f60 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
34f70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34f80 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
34f90 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
34fa0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
34fb0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
34fc0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
34fd0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
34fe0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
34ff0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
35000 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
35010 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
35020 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35030 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
35040 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
35050 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
35060 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35070 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35080 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
35090 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
350a0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
350b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
350c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
350d0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
350e0 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
350f0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
35100 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
35110 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
35120 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
35130 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
35140 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
35150 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35160 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
35170 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35180 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
35190 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
351a0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
351b0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
351c0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
351d0 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
351e0 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
351f0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
35200 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
35210 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35220 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
35230 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48  ary Data.** METH
35240 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
35250 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ext.**.** These 
35260 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
35270 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
35280 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
35290 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
352a0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
352b0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
352c0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
352d0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
352e0 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
352f0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
35300 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
35310 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
35320 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
35330 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
35340 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
35350 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
35360 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
35370 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
35380 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
35390 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
353a0 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
353b0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
353c0 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
353d0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
353e0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
353f0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
35400 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
35410 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
35420 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
35430 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
35440 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
35450 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
35460 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
35470 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
35480 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
35490 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
354a0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
354b0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
354c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
354d0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
354e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
354f0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
35500 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35510 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
35520 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
35530 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
35540 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35550 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
35560 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
35570 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
35580 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35590 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
355a0 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
355b0 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
355c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
355d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
355e0 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
355f0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
35600 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
35610 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
35620 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
35630 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35640 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
35650 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
35660 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
35670 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
35680 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
35690 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
356a0 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
356b0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
356c0 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
356d0 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
356e0 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
356f0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
35700 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35710 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
35720 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
35730 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
35740 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
35750 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
35760 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
35770 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
35780 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
35790 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
357a0 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
357b0 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
357c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
357d0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
357e0 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
357f0 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
35800 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
35810 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
35820 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
35830 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
35840 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
35850 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
35860 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
35870 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
35880 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
35890 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
358a0 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
358b0 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
358c0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
358d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
358e0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
358f0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
35900 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
35910 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
35920 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35930 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
35940 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
35950 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
35960 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
35970 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
35980 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
35990 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
359a0 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
359b0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
359c0 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
359d0 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
359e0 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
359f0 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
35a00 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
35a10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35a20 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
35a30 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
35a40 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
35a50 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
35a60 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
35a70 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
35a80 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
35a90 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35aa0 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
35ab0 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
35ac0 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
35ad0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35ae0 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
35af0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
35b00 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
35b10 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
35b20 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
35b30 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35b40 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
35b50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
35b60 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
35b70 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
35b80 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
35b90 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
35ba0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
35bb0 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
35bc0 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
35bd0 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
35be0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
35bf0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
35c00 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
35c10 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
35c20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
35c30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
35c40 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
35c50 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
35c60 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
35c70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
35c80 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
35c90 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
35ca0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
35cb0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
35cc0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
35cd0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
35ce0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
35cf0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
35d00 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
35d10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
35d20 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
35d30 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
35d40 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
35d50 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
35d60 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
35d70 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
35d80 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
35d90 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
35da0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
35db0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
35dc0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
35dd0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
35de0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
35df0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
35e00 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
35e10 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
35e20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
35e30 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
35e40 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
35e50 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
35e60 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
35e70 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
35e80 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
35e90 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
35ea0 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
35eb0 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
35ec0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
35ed0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
35ee0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
35ef0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
35f00 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
35f10 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
35f20 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
35f30 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
35f40 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
35f50 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
35f60 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
35f70 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70  ompilers..*/.typ
35f80 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
35f90 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
35fa0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
35fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
35fc0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
35fd0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
35fe0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
35ff0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
36000 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
36010 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
36020 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
36030 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
36040 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
36050 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  tion.** METHOD: 
36060 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
36070 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
36080 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
36090 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
360a0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
360b0 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
360c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
360d0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
360e0 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
360f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
36100 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36110 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36120 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
36130 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
36140 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
36150 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
36160 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
36170 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
36180 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
36190 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
361a0 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
361b0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
361c0 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
361d0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
361e0 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
361f0 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
36200 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
36210 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
36220 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
36230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36240 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
36250 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
36260 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
36270 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36280 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
36290 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
362a0 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
362b0 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
362c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
362d0 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
362e0 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
362f0 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
36300 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
36310 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36320 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43  esult_zeroblob(C
36330 2c 4e 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ,N) and sqlite3_
36340 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36  result_zeroblob6
36350 34 28 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66  4(C,N).** interf
36360 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
36370 75 6c 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ult of the appli
36380 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36390 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
363a0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
363b0 6e 67 20 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65  ng all zero byte
363c0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
363d0 20 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   size..**.** ^Th
363e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
363f0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
36400 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
36410 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
36420 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36430 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36440 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
36450 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
36460 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
36470 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
36480 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36490 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
364a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
364b0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
364c0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
364d0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
364e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
364f0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
36500 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
36510 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
36520 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
36530 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
36540 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
36550 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
36560 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36570 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
36580 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
36590 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
365a0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
365b0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
365c0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
365d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
365e0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
365f0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
36600 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
36610 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
36620 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
36630 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
36640 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
36650 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
36660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
36670 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36680 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
36690 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
366a0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
366b0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
366c0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
366d0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
366e0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
366f0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
36700 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
36710 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
36720 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
36730 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
36740 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
36750 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
36760 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
36770 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
36780 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
36790 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
367a0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
367b0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
367c0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
367d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
367e0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
367f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36800 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
36810 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
36820 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
36830 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
36840 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
36850 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
36860 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
36870 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
36880 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
36890 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
368a0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
368b0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
368c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
368d0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
368e0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
368f0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
36900 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
36910 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
36920 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
36930 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
36940 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
36950 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
36960 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
36970 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
36980 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
36990 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
369a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
369b0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
369c0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
369d0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
369e0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
369f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36a00 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  or_toobig() inte
36a10 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36a20 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
36a30 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
36a40 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
36a50 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
36a60 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
36a70 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36a80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36a90 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ror_nomem() inte
36aa0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36ab0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
36ac0 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
36ad0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
36ae0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
36af0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
36b00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
36b10 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
36b20 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36b30 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36b40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36b50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36b60 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
36b70 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
36b80 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
36b90 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
36ba0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36bb0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
36bc0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36bd0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36be0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
36bf0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36c00 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
36c10 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
36c20 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36c30 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36c40 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36c50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36c60 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
36c70 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36c80 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
36c90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36ca0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36cb0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
36cc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36cd0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
36ce0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36cf0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
36d00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
36d10 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
36d20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36d30 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
36d40 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
36d50 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
36d60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36d70 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36d80 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
36d90 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
36da0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
36db0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
36dc0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
36dd0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
36de0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
36df0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
36e00 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65  ctively..** ^The
36e10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36e20 74 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61  text64() interfa
36e30 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36e40 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a  rn value of an.*
36e50 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  * application-de
36e60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36e70 6f 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69  o be a text stri
36e80 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e  ng in an encodin
36e90 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62  g.** specified b
36ea0 79 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64  y the fifth (and
36eb0 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72   last) parameter
36ec0 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20  , which must be 
36ed0 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54  one.** of [SQLIT
36ee0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
36ef0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
36f00 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
36f10 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a  QLITE_UTF16LE]..
36f20 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
36f30 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
36f40 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
36f50 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
36f60 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
36f70 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
36f80 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36f90 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
36fa0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36fb0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
36fc0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
36fd0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
36fe0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
36ff0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
37000 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
37010 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
37020 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
37030 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
37040 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
37050 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37060 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37070 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37080 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
37090 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
370a0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
370b0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
370c0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
370d0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
370e0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
370f0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
37100 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
37110 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
37120 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
37130 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
37140 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
37150 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
37160 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
37170 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
37180 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
37190 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
371a0 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
371b0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
371c0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
371d0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
371e0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
371f0 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
37200 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
37210 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
37220 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
37230 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
37240 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
37250 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
37260 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
37270 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
37280 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
37290 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
372a0 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
372b0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
372c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
372d0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
372e0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
372f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
37300 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
37310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
37320 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
37330 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
37340 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
37350 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
37360 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
37370 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
37380 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
37390 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
373a0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
373b0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
373c0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
373d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
373e0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
373f0 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
37400 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
37410 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
37420 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
37430 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
37440 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
37450 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
37460 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
37470 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
37480 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
37490 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
374a0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
374b0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
374c0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
374d0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
374e0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
374f0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
37500 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
37510 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
37520 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37530 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
37540 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
37550 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
37560 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
37570 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
37580 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
37590 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
375a0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
375b0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
375c0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
375d0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
375e0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
375f0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
37600 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37610 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
37620 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
37630 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
37640 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37650 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37660 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
37670 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
37680 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37690 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
376a0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
376b0 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
376c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
376d0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
376e0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
376f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
37700 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
37710 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
37720 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
37730 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
37740 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
37750 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
37760 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
37770 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
37780 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
37790 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
377a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
377b0 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
377c0 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
377d0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
377e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
377f0 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
37800 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
37810 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
37820 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37830 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
37840 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
37850 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
37860 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
37870 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
37880 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
37890 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
378a0 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
378b0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
378c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
378d0 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
378e0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
378f0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
37900 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
37910 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
37920 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37930 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
37940 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37950 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
37960 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
37970 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37980 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  lt_blob64(sqlite
37990 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74  3_context*,const
379a0 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20   void*,.        
379b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
379c0 20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36     sqlite3_uint6
379d0 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  4,void(*)(void*)
379e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
379f0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
37a00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37a10 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
37a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37a30 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
37a40 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37a50 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
37a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37a70 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
37a80 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37a90 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
37aa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37ab0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
37ac0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
37ad0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37ae0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
37af0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
37b00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37b10 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
37b20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37b30 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
37b40 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
37b50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37b60 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
37b70 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
37b80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37b90 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
37ba0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37bb0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
37bc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
37bd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37be0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
37bf0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37c00 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
37c10 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
37c20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37c30 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
37c40 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37c50 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
37c60 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
37c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37c80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
37c90 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
37ca0 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73  ncoding);.void s
37cb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37cc0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
37cd0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
37ce0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
37cf0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
37d00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37d10 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
37d20 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37d30 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
37d40 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
37d50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37d60 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
37d70 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37d80 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
37d90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37da0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37db0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
37dc0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
37dd0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
37de0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
37df0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
37e00 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
37e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 75  int sqlite3_resu
37e20 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  lt_zeroblob64(sq
37e30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37e40 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 6e  sqlite3_uint64 n
37e50 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
37e60 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
37e70 20 53 75 62 74 79 70 65 20 4f 66 20 41 6e 20 53   Subtype Of An S
37e80 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d  QL Function.** M
37e90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
37ea0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65  ontext.**.** The
37eb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37ec0 73 75 62 74 79 70 65 28 43 2c 54 29 20 66 75 6e  subtype(C,T) fun
37ed0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
37ee0 20 73 75 62 74 79 70 65 20 6f 66 0a 2a 2a 20 74   subtype of.** t
37ef0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  he result from t
37f00 68 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  he [application-
37f10 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37f20 74 69 6f 6e 5d 20 77 69 74 68 20 0a 2a 2a 20 5b  tion] with .** [
37f30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
37f40 20 43 20 74 6f 20 62 65 20 74 68 65 20 76 61 6c   C to be the val
37f50 75 65 20 54 2e 20 20 4f 6e 6c 79 20 74 68 65 20  ue T.  Only the 
37f60 6c 6f 77 65 72 20 38 20 62 69 74 73 20 0a 2a 2a  lower 8 bits .**
37f70 20 6f 66 20 74 68 65 20 73 75 62 74 79 70 65 20   of the subtype 
37f80 54 20 61 72 65 20 70 72 65 73 65 72 76 65 64 20  T are preserved 
37f90 69 6e 20 63 75 72 72 65 6e 74 20 76 65 72 73 69  in current versi
37fa0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 3b 0a 2a  ons of SQLite;.*
37fb0 2a 20 68 69 67 68 65 72 20 6f 72 64 65 72 20 62  * higher order b
37fc0 69 74 73 20 61 72 65 20 64 69 73 63 61 72 64 65  its are discarde
37fd0 64 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72  d..** The number
37fe0 20 6f 66 20 73 75 62 74 79 70 65 20 62 79 74 65   of subtype byte
37ff0 73 20 70 72 65 73 65 72 76 65 64 20 62 79 20 53  s preserved by S
38000 51 4c 69 74 65 20 6d 69 67 68 74 20 69 6e 63 72  QLite might incr
38010 65 61 73 65 0a 2a 2a 20 69 6e 20 66 75 74 75 72  ease.** in futur
38020 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
38030 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  Lite..*/.void sq
38040 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
38050 74 79 70 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  type(sqlite3_con
38060 74 65 78 74 2a 2c 75 6e 73 69 67 6e 65 64 20 69  text*,unsigned i
38070 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
38080 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
38090 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
380a0 6e 63 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  nces.** METHOD: 
380b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
380c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
380d0 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
380e0 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
380f0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
38100 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
38110 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38120 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
38130 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38140 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
38150 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
38160 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
38170 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
38180 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
38190 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
381a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
381b0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
381c0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
381d0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
381e0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
381f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38200 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
38210 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
38220 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
38230 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
38240 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
38250 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
38260 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
38270 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
38280 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
38290 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
382a0 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
382b0 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
382c0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
382d0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
382e0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
382f0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
38300 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
38310 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
38320 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
38330 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
38340 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
38350 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
38360 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
38370 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
38380 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
38390 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
383a0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
383b0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
383c0 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
383d0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
383e0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
383f0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
38400 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
38410 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
38420 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
38430 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
38440 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
38450 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
38460 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
38470 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
38480 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
38490 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
384a0 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
384b0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
384c0 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
384d0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
384e0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
384f0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
38500 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
38510 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
38520 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
38530 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
38540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
38550 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
38560 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
38570 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
38580 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
38590 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
385a0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
385b0 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
385c0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
385d0 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
385e0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
385f0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
38600 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
38610 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
38620 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
38630 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
38640 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
38650 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
38660 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
38670 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
38680 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
38690 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
386a0 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
386b0 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
386c0 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
386d0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
386e0 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
386f0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
38700 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
38710 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
38720 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
38730 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
38740 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
38750 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
38760 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
38770 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
38780 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
38790 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
387a0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
387b0 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
387c0 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
387d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
387e0 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
387f0 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
38800 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
38810 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
38820 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
38830 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
38840 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
38850 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
38860 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
38870 63 7