System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 9233f3b3b811fc4722290126836954302500da1c:


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 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e  ** Since version
0f00: 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20   3.6.18, SQLite 
0f10: 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73 20  source code has 
0f20: 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74  been stored in t
0f30: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68  he.** <a href="h
0f40: 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c  ttp://www.fossil
0f50: 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69  -scm.org/">Fossi
0f60: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  l configuration 
0f70: 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79  management.** sy
0f80: 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20  stem</a>.  ^The 
0f90: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
0fa0: 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73   macro evaluates
0fb0: 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20   to.** a string 
0fc0: 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65 73  which identifies
0fd0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 68   a particular ch
0fe0: 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65  eck-in of SQLite
0ff0: 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63  .** within its c
1000: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e  onfiguration man
1010: 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20  agement system. 
1020: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
1030: 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67  RCE_ID.** string
1040: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
1050: 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74  te and time of t
1060: 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43  he check-in (UTC
1070: 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a  ) and an SHA1.**
1080: 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74   hash of the ent
1090: 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ire source tree.
10a0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
10b0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
10c0: 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sion()],.** [sql
10d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
10e0: 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69  number()], [sqli
10f0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c  te3_sourceid()],
1100: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  .** [sqlite_vers
1110: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
1120: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
1130: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
1150: 20 20 22 33 2e 31 34 2e 30 22 0a 23 64 65 66 69    "3.14.0".#defi
1160: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1170: 4e 5f 4e 55 4d 42 45 52 20 33 30 31 34 30 30 30  N_NUMBER 3014000
1180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1190: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11a0: 32 30 31 36 2d 30 38 2d 30 38 20 31 33 3a 34 30  2016-08-08 13:40
11b0: 3a 32 37 20 64 35 65 39 38 30 35 37 30 32 38 61  :27 d5e98057028a
11c0: 62 63 66 37 32 31 37 64 30 64 32 62 32 65 32 39  bcf7217d0d2b2e29
11d0: 62 62 62 63 64 66 30 39 64 36 64 65 22 0a 0a 2f  bbbcdf09d6de"../
11e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
11f0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1200: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
1210: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1220: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
17c0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
17d0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
17e0: 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  ];.SQLITE_API co
17f0: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
1800: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1810: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
1820: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1830: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
1840: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1850: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b  _sourceid(void);
1860: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1870: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1880: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1890: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
18a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18b0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
18c0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
18d0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
18e0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
18f0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1900: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1910: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1920: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1930: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1940: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1950: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1960: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1970: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1980: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1990: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
19a0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
19b0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
19c0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
19d0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
19e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
19f0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1a00: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1a10: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1a20: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1a30: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1a40: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1a50: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1a60: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1a70: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1a80: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1a90: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1aa0: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1ab0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ac0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1ad0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1ae0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1af0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1b00: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1b10: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1b20: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b30: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1b40: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1b50: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1b60: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1b70: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b80: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1b90: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ba0: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1bb0: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1bc0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1bd0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1be0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1bf0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1c00: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1c10: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1c20: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1c40: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1c50: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1c60: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1c70: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1c80: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1c90: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ca0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1cb0: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  GS.SQLITE_API in
1cc0: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1cf0: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1d00: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1d10: 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
1d20: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1d50: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1d60: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1d70: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1d80: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1d90: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1da0: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1db0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1dc0: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1dd0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1de0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1df0: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
1e00: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
1e10: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e20: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
1e30: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
1e40: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
1e50: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
1e60: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
1e70: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
1e80: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
1e90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1ea0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1eb0: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
1ec0: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
1ed0: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
1ee0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
1ef0: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
1f00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f10: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
1f20: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1f30: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1f40: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1f50: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1f60: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
1f70: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
1f80: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
1f90: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
1fa0: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1fb0: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1fc0: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1fd0: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1fe0: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1ff0: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
2000: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
2010: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
2020: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
2030: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
2040: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
2050: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
2060: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
2070: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
2080: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
2090: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
20a0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
20b0: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
20c0: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
20d0: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
20e0: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
20f0: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
2100: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
2110: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2120: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
2130: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
2140: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2150: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
2160: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
2170: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
2180: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2190: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
21a0: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
21b0: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
21c0: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
21d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
21e0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
21f0: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
2200: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
2210: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
2220: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
2230: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
2240: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
2250: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2260: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
2270: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
2280: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2290: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
22a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
22b0: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
22c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
22d0: 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68  RIALIZED].  ^(Th
22e0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
22f0: 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  f the.** sqlite3
2300: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
2310: 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c  nction shows onl
2320: 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  y the compile-ti
2330: 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a  me setting of.**
2340: 20 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20   thread safety, 
2350: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65  not any run-time
2360: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74   changes to that
2370: 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79   setting made by
2380: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  .** sqlite3_conf
2390: 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77  ig(). In other w
23a0: 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e  ords, the return
23b0: 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
23c0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
23d0: 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64  .** is unchanged
23e0: 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   by calls to sql
23f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e  ite3_config().)^
2400: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  .**.** See the [
2410: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
2420: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
2430: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2440: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  ormation..*/.SQL
2450: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2460: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2470: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
2480: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
2490: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
24a0: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
24b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
24c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24d0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
24e0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
24f0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
2500: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
2510: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
2520: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
2530: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
2540: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
2550: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
2560: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
2570: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
2580: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
2590: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
25a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
25b0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
25c0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
25d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
25e0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
25f0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
2600: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
2610: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
2620: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2630: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73  se_v2()] are its
2640: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54   destructors.  T
2650: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
2660: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  her.** interface
2670: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2680: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2690: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
26a0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
26b0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26c0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
26d0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
26e0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
26f0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
2700: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
2710: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2720: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2730: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2740: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2750: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2760: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2770: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2780: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2790: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
27a0: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
27b0: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
27c0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
27d0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
27e0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
27f0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
2800: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
2810: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
2820: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2830: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2840: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2850: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2860: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2870: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2880: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2890: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
28a0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
28b0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
28c0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28d0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
28e0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
28f0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2900: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
2910: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
2920: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2930: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2940: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2950: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2960: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2970: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2980: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2990: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
29a0: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
29b0: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
29c0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
29d0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
29e0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
29f0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2a00: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2a10: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2a20: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2a30: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2a40: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2a50: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2a60: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2a70: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2a80: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2aa0: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2ab0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2ac0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2ad0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2ae0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2af0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2b00: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2b10: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2b20: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2b30: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2b40: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2b50: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2b60: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2b70: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2b80: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2b90: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2ba0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2bb0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2bc0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2bd0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2be0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2bf0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2c00: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2c10: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2c20: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2c30: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2c40: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2c50: 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43  ction.** DESTRUC
2c60: 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
2c70: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c80: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2ca0: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74  outines are dest
2cb0: 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74  ructors.** for t
2cc0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2cd0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2ce0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2cf0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2d00: 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20  ose_v2() return 
2d10: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a  [SQLITE_OK] if.*
2d20: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
2d30: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73  object is succes
2d40: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
2d50: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
2d60: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73  ted.** resources
2d70: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64   are deallocated
2d80: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2d90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2da0: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65  ion is associate
2db0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2dc0: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  ed prepared.** s
2dd0: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66  tatements or unf
2de0: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2df0: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74  backup objects t
2e00: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  hen sqlite3_clos
2e10: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76  e().** will leav
2e20: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
2e30: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61  onnection open a
2e40: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
2e50: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20  E_BUSY]..** ^If 
2e60: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2e70: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
2e80: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
2e90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ea0: 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69  s.** and/or unfi
2eb0: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2ec0: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
2ed0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ee0: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
2ef0: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
2f00: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
2f10: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
2f20: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
2f30: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
2f40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f50: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
2f60: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
2f70: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
2f80: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
2f90: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2fa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
2fb0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
2fc0: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
2fd0: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
2fe0: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
2ff0: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
3000: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
3010: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
3020: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
3030: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
3040: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
3050: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
3060: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
3070: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
3080: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
3090: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
30a0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
30b0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
30c0: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
30d0: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
30e0: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
30f0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3100: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
3110: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
3120: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
3130: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
3140: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
3150: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
3160: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3170: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  is called on a [
3180: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3190: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20  ion] that still 
31a0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  has.** outstandi
31b0: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ng [prepared sta
31c0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
31d0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72  handles], and/or
31e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31f0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65  kup] objects the
3200: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51  n it returns [SQ
3210: 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65  LITE_OK] and the
3220: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
3230: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
3240: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3250: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3260: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3270: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3280: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3290: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
32a0: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
32b0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
32c0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
32d0: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
32e0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
32f0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
3300: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
3310: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
3320: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
3330: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
3340: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3350: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3360: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3370: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3380: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3390: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
33a0: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
33b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
33c0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
33e0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
33f0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
3400: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
3410: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
3420: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
3430: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
3440: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3450: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3460: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3470: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3480: 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  -op..*/.SQLITE_A
3490: 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
34a0: 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c  DCALL sqlite3_cl
34b0: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  ose(sqlite3*);.S
34c0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34d0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34e0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
34f0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3500: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3510: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3520: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
3530: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
3540: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
3550: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
3560: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
3570: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
3580: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
3590: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
35a0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
35b0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
35c0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
35d0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
35e0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
35f0: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  on Interface.** 
3600: 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
3610: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3620: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
3630: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
3640: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
3650: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
3660: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
3670: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
3680: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3690: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
36a0: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
36b0: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
36c0: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
36d0: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
36e0: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
36f0: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3700: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3710: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3720: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
3730: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
3740: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
3750: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
3760: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
3770: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
3780: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3790: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
37a0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
37b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
37c0: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
37d0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
37e0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
37f0: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3800: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3810: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3820: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
3830: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
3840: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
3850: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
3860: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
3870: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
3880: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3890: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
38a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
38b0: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
38c0: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
38d0: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
38e0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
38f0: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3900: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3910: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3920: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
3930: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
3940: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
3950: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
3960: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
3970: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
3980: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3990: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
39a0: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
39b0: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
39c0: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
39d0: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
39e0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
39f0: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3a00: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3a10: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3a20: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
3a30: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a40: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3a50: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
3a60: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
3a70: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
3a80: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3a90: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3aa0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3ab0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3ac0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3ad0: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3ae0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3af0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3b00: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3b10: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3b20: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
3b30: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
3b40: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
3b50: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
3b60: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  f.** sqlite3_exe
3b70: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
3b80: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
3b90: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
3ba0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
3bb0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3bc0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3bd0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3be0: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3bf0: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3c00: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3c10: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3c20: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
3c30: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
3c40: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
3c50: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
3c60: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3c70: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
3c80: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3c90: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3ca0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3cb0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3cc0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3cd0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3ce0: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3cf0: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3d00: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3d10: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3d20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3d40: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3d50: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3d60: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3d70: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3d80: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3d90: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3da0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3db0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3dc0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3dd0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3de0: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3df0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3e00: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3e10: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3e20: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3e30: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3e40: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3e50: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3e60: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3e70: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3e80: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3e90: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3ea0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3eb0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3ec0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3ed0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3ee0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3ef0: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3f00: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3f10: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3f20: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3f30: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3f40: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3f50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3f60: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3f70: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3f80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3f90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3fa0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3fb0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3fc0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3fd0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3fe0: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3ff0: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
4000: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
4010: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
4020: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
4030: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
4040: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
4050: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
4060: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
4070: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
4080: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
4090: 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  on must ensure t
40a0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
40b0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
40c0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
40d0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
40e0: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
40f0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
4100: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
4110: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
4120: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
4130: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
4140: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
4150: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
4160: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4170: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
4180: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
4190: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
41a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
41b0: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
41c0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
41d0: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
41e0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
41f0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
4200: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
4210: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
4220: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
4230: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
4240: 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
4250: 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
4260: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4270: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4290: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
42a0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
42b0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
42c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42d0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
42e0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
42f0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4300: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4310: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4320: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4330: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
4340: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4360: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4370: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4380: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4390: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
43a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
43b0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
43c0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
43d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
43e0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
43f0: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4400: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4410: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4420: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4430: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4440: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4450: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4460: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4470: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4480: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4490: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
44a0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
44b0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
44c0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
44d0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
44e0: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
44f0: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4500: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4510: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4520: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4530: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
4540: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
4550: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4570: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4580: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
4590: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
45a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
45b0: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
45c0: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
45d0: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
45e0: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
45f0: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4600: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4610: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4620: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4630: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4640: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
4650: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
4660: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4680: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4690: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
46a0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
46b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46c0: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
46d0: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
46e0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
46f0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4700: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4710: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4720: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4740: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
4750: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
4760: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4770: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4790: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
47a0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
47b0: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
47c0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
47d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
47e0: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
47f0: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4800: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4810: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4830: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4840: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
4850: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
4860: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4870: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4880: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4890: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
48a0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
48b0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
48c0: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
48d0: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
48e0: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
48f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4900: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4910: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4920: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4930: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4940: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4950: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
4960: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4970: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4980: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
49a0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
49b0: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
49c0: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
49d0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
49e0: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
49f0: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a00: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4a10: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4a20: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4a30: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4a40: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4a70: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4a80: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4a90: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4aa0: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4ab0: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4ac0: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4ad0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ae0: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4af0: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b00: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b20: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4b30: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4b40: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4b50: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4b60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4b70: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4b80: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4b90: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4ba0: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4bb0: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4bc0: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4bd0: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4bf0: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4c00: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4c10: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4c20: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4c30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4c40: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4c50: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4c60: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4c70: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4c80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4c90: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4ca0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4cb0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4cc0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4cd0: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4ce0: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4cf0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4d00: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4d10: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4d20: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4d30: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4d40: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4d50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4d60: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4d70: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4d80: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4d90: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4da0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4db0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4dc0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4dd0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4de0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4df0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4e00: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4e10: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4e20: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4e30: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4e40: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4e50: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4e60: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4e70: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4e80: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4e90: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4ea0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4eb0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4ec0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4ed0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4ee0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4ef0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4f00: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4f10: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4f20: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4f30: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4f40: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4f50: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4f60: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4f70: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4f80: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4f90: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4fa0: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4fb0: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4fc0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4fd0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4fe0: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4ff0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
5000: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
5010: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
5020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5030: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
5040: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5050: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
5060: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
5070: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
5080: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
5090: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
50a0: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
50b0: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
50c0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
50d0: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
50e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50f0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
5100: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5110: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5120: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5130: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
5140: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5150: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5160: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
5170: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
5180: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5190: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
51a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
51b0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
51c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51d0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
51e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
51f0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
5200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5210: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5220: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
5230: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
5240: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
5250: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5260: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
5270: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5280: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
5290: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52a0: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
52b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
52c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
52d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
52e0: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
52f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5300: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5310: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5320: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5330: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5340: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
5350: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5360: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
5370: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5380: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
5390: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53a0: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
53b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53c0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
53d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53e0: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
53f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5400: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5410: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5420: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5430: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
5440: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
5450: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5460: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
5470: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5480: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
5490: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54a0: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
54b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54c0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
54d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54e0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
54f0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5500: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5510: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5520: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5530: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5540: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
5550: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5560: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
5570: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5580: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
5590: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55a0: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
55b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55c0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
55d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55e0: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
55f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5600: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5610: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5620: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5630: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5640: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5660: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
5670: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
5680: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
5690: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56a0: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
56b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
56c0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
56d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56e0: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
56f0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5700: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5710: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5720: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5730: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5740: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
5750: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5760: 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20  E_IOERR_VNODE   
5770: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5780: 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38  E_IOERR | (27<<8
5790: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57a0: 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20  E_IOERR_AUTH    
57b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57c0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38  E_IOERR | (28<<8
57d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57e0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
57f0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
5800: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
5810: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5820: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5830: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5840: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5850: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5860: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5870: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5880: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5890: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
58b0: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
58c0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
58d0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
58e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
58f0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
5900: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5910: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5920: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5930: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5940: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5950: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5970: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5980: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5990: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
59b0: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
59d0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
59e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
59f0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
5a00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5a10: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a30: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5a40: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5a50: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5a80: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5a90: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5aa0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ab0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
5ac0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
5ad0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5ae0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5af0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5b00: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5b10: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5b20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b40: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5b50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b60: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b80: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5b90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ba0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bc0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5bd0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5be0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5bf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c00: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5c10: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5c20: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5c30: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c40: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5c50: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5c60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c70: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5c80: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5c90: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5ca0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5cb0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5cc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5cd0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
5ce0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5cf0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
5d00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5d20: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5d30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5d40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5d60: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5d70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5d80: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5d90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5da0: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5db0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5dc0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5de0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5e00: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5e20: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5e30: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5e40: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5e60: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5e80: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5e90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5ea0: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5eb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ec0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
5ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
5ee0: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
5ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
5f00: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
5f10: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
5f20: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
5f30: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
5f40: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5f50: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5f60: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5f70: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5f80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5f90: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5fa0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5fb0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5fc0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
5fd0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
5fe0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5ff0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
6000: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6010: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
6020: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6030: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6040: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
6050: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6060: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
6070: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6080: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6090: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
60a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
60b0: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
60c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
60d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
60e0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
60f0: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
6100: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
6110: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6120: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
6130: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
6140: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
6150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6160: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
6170: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
6180: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
6190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61a0: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
61b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
61c0: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
61d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
61e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
61f0: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
6200: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6210: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
6220: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6230: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6240: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
6250: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6260: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
6270: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6280: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
6290: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
62a0: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
62b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
62c0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
62d0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
62e0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
62f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6300: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
6310: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
6320: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
6330: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6340: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
6350: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
6360: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6370: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6380: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
6390: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
63a0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
63b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
63c0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
63d0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
63e0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
63f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6400: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
6410: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
6420: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6430: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6450: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
6460: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
6470: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6480: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64a0: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
64b0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
64c0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
64d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
64e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
64f0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
6500: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
6510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
6520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6540: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
6550: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
6560: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
6570: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
6580: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
6590: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
65a0: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
65b0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
65c0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
65d0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
65e0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
65f0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
6600: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6610: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
6620: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
6630: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
6640: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
6650: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
6660: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
6670: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
6680: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
6690: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
66a0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
66b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
66c0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
66d0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
66e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
66f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6700: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6710: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6720: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6730: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6740: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6750: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6760: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6770: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6780: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6790: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
67a0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
67b0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
67c0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
67d0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
67e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
67f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6800: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6810: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6820: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6830: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6840: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6850: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6860: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
6870: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
6880: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
6890: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
68a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
68b0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
68c0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
68d0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
68e0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
68f0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
6900: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
6910: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
6920: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6930: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
6940: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6950: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
6960: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
6970: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
6980: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
6990: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
69a0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
69b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
69c0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
69d0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
69e0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
69f0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
6a00: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
6a10: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
6a20: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
6a30: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
6a40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6a50: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6a60: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
6a70: 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63  te that a file c
6a80: 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64  annot be deleted
6a90: 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65   when open.  The
6aa0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  .** SQLITE_IOCAP
6ab0: 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20  _IMMUTABLE flag 
6ac0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
6ad0: 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a  he file is on.**
6ae0: 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61   read-only media
6af0: 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63   and cannot be c
6b00: 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70  hanged even by p
6b10: 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a  rocesses with.**
6b20: 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c   elevated privil
6b30: 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  eges..*/.#define
6b40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6b50: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6b60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6b70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b80: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6b90: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ba0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
6bb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6bc0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
6bd0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
6be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6bf0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
6c00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6c10: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6c20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6c30: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6c40: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c60: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6c70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6c80: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6c90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6cb0: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
6cc0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6cd0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
6ce0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6cf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6d00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
6d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6d20: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6d30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6d40: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6d50: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6d70: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6d80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6d90: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6da0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6db0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6dc0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6de0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6df0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6e00: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
6e10: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6e20: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  LE              
6e30: 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a  0x00002000../*.*
6e40: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
6e50: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6e60: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6e70: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6e80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6e90: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6ea0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6eb0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6ec0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6ed0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6ee0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6ef0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6f00: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6f10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6f20: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6f30: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6f40: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
6f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6f60: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6f70: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6f80: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6f90: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6fa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6fb0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6fc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6fd0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6fe0: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6ff0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
7000: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
7010: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
7020: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7030: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
7040: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
7050: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
7060: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7070: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
7080: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
7090: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
70a0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
70b0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
70c0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
70d0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
70e0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
70f0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
7100: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
7110: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
7120: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
7130: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7140: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
7150: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
7160: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
7170: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
7180: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
7190: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
71a0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
71b0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
71c0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
71d0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
71e0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
71f0: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
7200: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
7210: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
7220: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
7230: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7240: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7250: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
7260: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7270: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
7280: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7290: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
72a0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
72b0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
72c0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
72d0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
72e0: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
72f0: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
7300: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
7310: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
7320: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
7330: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7340: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7350: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
7360: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
7370: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
7380: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
7390: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
73a0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
73b0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
73c0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
73d0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
73e0: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
73f0: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
7400: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
7410: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7420: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7430: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7440: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7450: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7460: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7470: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
7480: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
7490: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
74a0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
74b0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
74c0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
74d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
74e0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
74f0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
7500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7510: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7520: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7530: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7540: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7550: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7560: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7570: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
7580: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
7590: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
75a0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
75b0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
75c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
75d0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
75e0: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
75f0: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
7600: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7610: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7620: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7630: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7640: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7650: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7660: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7670: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7680: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7690: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
76a0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
76b0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
76c0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
76d0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
76e0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
76f0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7700: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7710: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7720: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7730: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7740: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7750: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7760: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7770: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7780: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7790: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
77a0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
77b0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
77c0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
77d0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
77e0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
77f0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7800: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7810: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7820: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7830: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7840: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7850: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7860: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7870: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7880: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7890: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
78a0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
78b0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
78c0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
78d0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
78e0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
78f0: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7900: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7910: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7920: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7930: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7940: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7950: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7960: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7970: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7980: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7990: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
79a0: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
79b0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
79c0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
79d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
79e0: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
79f0: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7a00: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7a10: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7a20: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7a30: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7a40: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7a50: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7a60: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a70: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7a80: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7a90: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7aa0: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7ab0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7ac0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7ad0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7ae0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7af0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7b00: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
7b10: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7b20: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7b30: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7b40: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
7b50: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7b60: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7b70: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7b80: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7b90: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7ba0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7bb0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
7bc0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
7bd0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
7be0: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
7bf0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
7c00: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
7c10: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
7c20: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
7c30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7c40: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
7c50: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7c60: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7c70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7c80: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7c90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7ca0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7cb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7cc0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7cd0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7ce0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7cf0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
7d00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
7d10: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
7d20: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
7d30: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
7d40: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
7d50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7d60: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7d70: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7d80: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7d90: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7da0: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7db0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7dc0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7dd0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7de0: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7df0: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
7e00: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
7e10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
7e20: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
7e30: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
7e40: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
7e50: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7e60: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7e70: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7e80: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7e90: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7eb0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7ec0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7ed0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7ee0: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7ef0: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7f00: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7f10: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7f20: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7f30: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7f40: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
7f50: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
7f60: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7f70: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7f80: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7f90: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7fa0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7fb0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7fc0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7fd0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7fe0: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7ff0: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
8000: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
8010: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
8020: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
8030: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
8040: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
8050: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
8060: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
8070: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
8080: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
8090: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
80a0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
80b0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
80c0: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ** A [file contr
80d0: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73  ol opcodes | lis
80e0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
80f0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
8100: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
8110: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
8120: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
8130: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8140: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
8150: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
8160: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
8170: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
8180: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
8190: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
81a0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
81b0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
81c0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
81d0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
81e0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
81f0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8200: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8210: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8220: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8230: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8240: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8250: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8260: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8270: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
8280: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
8290: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
82a0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
82b0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
82c0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
82d0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
82e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
82f0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8300: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8310: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8320: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8330: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8350: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8360: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8370: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
8380: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8390: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
83a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83b0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
83c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83d0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
83e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83f0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8410: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8420: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8430: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8440: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8450: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8460: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8470: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
8480: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8490: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
84a0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
84b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
84c0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
84d0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
84e0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
84f0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
8500: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8510: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8520: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8530: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8540: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8550: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8560: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8570: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
8580: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
8590: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
85a0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
85b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
85c0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
85d0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
85e0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
85f0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
8600: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
8610: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8620: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8630: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8640: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8650: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8660: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8670: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8680: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
8690: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
86a0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
86b0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
86c0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
86d0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
86e0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
86f0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
8700: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
8710: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8720: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8730: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8740: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8750: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8760: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8770: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8780: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
8790: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
87a0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
87b0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
87c0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
87d0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
87e0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
87f0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
8800: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8810: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8820: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8830: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8840: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8850: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8860: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8870: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8880: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8890: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
88a0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
88b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
88c0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
88d0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
88e0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
88f0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8900: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8910: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8920: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8930: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8940: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8950: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8960: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8970: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8980: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8990: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
89a0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
89b0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
89c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
89d0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
89e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
89f0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
8a00: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8a10: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8a20: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8a30: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8a40: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8a50: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8a60: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8a70: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8a80: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8a90: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8aa0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
8ab0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8ac0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8ad0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8ae0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
8af0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
8b00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8b10: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8b20: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8b30: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8b40: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8b50: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8b60: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8b70: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
8b80: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8b90: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8ba0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
8bb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8bc0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
8bd0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8be0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8bf0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
8c00: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
8c10: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8c20: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8c30: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8c40: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8c50: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8c60: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8c70: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8c80: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8c90: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8ca0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8cb0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
8cc0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
8cd0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
8ce0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
8cf0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8d00: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
8d10: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8d20: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
8d30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8d40: 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74  odes} {file cont
8d50: 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a  rol opcode}.**.*
8d60: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8d70: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
8d80: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
8d90: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8da0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8db0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8dc0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8dd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8de0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8df0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
8e00: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53   <ul>.** <li>[[S
8e10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8e20: 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  STATE]].** The [
8e30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8e40: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
8e50: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
8e60: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8e70: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8e80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8e90: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8ea0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8eb0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8ec0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8ed0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8ee0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8ef0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8f00: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
8f10: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8f20: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
8f30: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
8f40: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
8f50: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
8f60: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
8f70: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
8f80: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
8f90: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
8fa0: 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  d is only availa
8fb0: 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c  ble when the SQL
8fc0: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70  ITE_TEST.** comp
8fd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
8fe0: 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
8ff0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9000: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
9010: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9020: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
9030: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
9040: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
9050: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
9060: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
9070: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
9080: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
9090: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
90a0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
90b0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
90c0: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
90d0: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
90e0: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
90f0: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
9100: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
9110: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
9120: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
9130: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
9140: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
9150: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
9160: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
9170: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9180: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
9190: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
91a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
91b0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
91c0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
91d0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
91e0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
91f0: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
9200: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
9210: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
9220: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
9230: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
9240: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
9250: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
9260: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
9270: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
9280: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
9290: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
92a0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
92b0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
92c0: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
92d0: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
92e0: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
92f0: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
9300: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
9310: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
9320: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
9330: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
9340: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
9350: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
9360: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
9370: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
9380: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
9390: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
93a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
93b0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
93c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
93d0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
93e0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
93f0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9400: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9410: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9420: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9430: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9440: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9450: 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b  ion.  See also [
9460: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9470: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  RNAL_POINTER]..*
9480: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9490: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
94a0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
94b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
94c0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20  OURNAL_POINTER] 
94d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
94e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
94f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9500: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9510: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9520: 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66  th the journal f
9530: 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74  ile (either.** t
9540: 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75  he [rollback jou
9550: 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72  rnal] or the [wr
9560: 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20  ite-ahead log]) 
9570: 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
9580: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9590: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
95a0: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
95b0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a  _FILE_POINTER]..
95c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
95d0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
95e0: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
95f0: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9600: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9610: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9620: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9630: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9640: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9650: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
9660: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
9670: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
9680: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
9690: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
96a0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
96b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
96c0: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
96d0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
96e0: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
96f0: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9700: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9710: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9720: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9730: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9740: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
9750: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
9760: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
9770: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9780: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
9790: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
97a0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
97b0: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
97c0: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
97d0: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
97e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
97f0: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9800: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9810: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9820: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9830: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9840: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
9850: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
9860: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
9870: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
9880: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
9890: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
98a0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
98b0: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
98c0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
98d0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
98e0: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
98f0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9900: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9910: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9920: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9930: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9940: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
9950: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9960: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9970: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9980: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9990: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
99a0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
99b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
99c0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
99d0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
99e0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
99f0: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9a00: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9a10: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9a20: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9a30: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9a40: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
9a50: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
9a60: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
9a70: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
9a80: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
9a90: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9aa0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9ab0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9ac0: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9ad0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9ae0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9af0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9b00: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9b10: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9b20: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9b30: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9b40: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9b50: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
9b60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
9b70: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
9b80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9b90: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9ba0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9bb0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9bc0: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9bd0: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9be0: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9bf0: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9c00: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9c10: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9c20: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9c30: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9c40: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
9c50: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
9c60: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
9c70: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
9c80: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
9c90: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
9ca0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9cb0: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9cc0: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9cd0: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9ce0: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9cf0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9d00: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9d10: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9d20: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9d30: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9d40: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
9d50: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
9d60: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
9d70: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
9d80: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
9d90: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
9da0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9db0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9dc0: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9dd0: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9de0: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9df0: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9e00: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9e10: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9e20: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9e30: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9e40: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
9e50: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
9e60: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
9e70: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
9e80: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9e90: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9ea0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9eb0: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9ec0: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9ed0: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9ee0: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9ef0: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9f00: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9f10: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9f20: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9f30: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9f40: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9f50: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9f60: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9f70: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9f80: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9f90: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9fa0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9fb0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9fc0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9fd0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9fe0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9ff0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a000: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a010: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a020: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a030: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a040: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a050: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a060: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a070: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
a080: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
a090: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a0a0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a0b0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a0c0: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a0d0: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a0e0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a0f0: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a100: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a110: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a120: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a130: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a140: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a150: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a160: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a170: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a180: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a190: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a1a0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a1b0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a1c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a1d0: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a1e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a1f0: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a200: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a210: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a220: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a230: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a240: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
a250: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a260: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a270: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a280: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a290: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a2a0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a2b0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a2c0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a2d0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
a2e0: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
a2f0: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
a300: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
a310: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a320: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a330: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a340: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a350: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
a360: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a370: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a380: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a390: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a3a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a3b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a3c0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
a3d0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a3e0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a3f0: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
a400: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
a410: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
a420: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
a430: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
a440: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
a450: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a460: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
a470: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
a480: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
a490: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
a4a0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a4b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a4c0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a4d0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a4e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a4f0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a500: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a510: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a520: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a530: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a540: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a550: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a560: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a570: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a580: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a590: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a5a0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a5b0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a5c0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a5d0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a5e0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a5f0: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a600: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a610: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a620: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a630: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a640: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a650: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a660: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a670: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a680: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a690: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a6a0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a6b0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a6c0: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a6d0: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a6e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a6f0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a700: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a710: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a720: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a730: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a740: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a750: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a760: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a770: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a780: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a790: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a7a0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a7b0: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a7c0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a7d0: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a7e0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a7f0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a800: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a810: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a820: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a830: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a840: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a850: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a860: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a870: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a880: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a890: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a8a0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a8b0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a8c0: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a8d0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a8e0: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a8f0: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a900: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a910: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a920: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a930: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a940: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a950: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a960: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a970: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a980: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a990: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a9a0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a9b0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a9c0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
a9d0: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
a9e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
a9f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
aa00: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
aa10: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
aa20: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
aa30: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
aa40: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
aa50: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
aa60: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
aa70: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
aa80: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
aa90: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
aaa0: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
aab0: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
aac0: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
aad0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
aae0: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
aaf0: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
ab00: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
ab10: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
ab20: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
ab30: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
ab40: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
ab50: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
ab60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab70: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
ab80: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
ab90: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
aba0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
abb0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
abc0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
abd0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
abe0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
abf0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
ac00: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
ac10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
ac20: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
ac30: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
ac40: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
ac50: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
ac60: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ac70: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
ac80: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
ac90: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
aca0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
acb0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
acc0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
acd0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
ace0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
acf0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
ad00: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
ad10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
ad20: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
ad30: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
ad40: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
ad50: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
ad60: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
ad70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ad80: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
ad90: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
ada0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
adb0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
adc0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
add0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
ade0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
adf0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
ae00: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
ae10: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
ae20: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
ae30: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
ae40: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
ae50: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
ae60: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
ae70: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
ae80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
ae90: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
aea0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
aeb0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
aec0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
aed0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
aee0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
aef0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
af00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
af10: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
af20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
af30: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
af40: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
af50: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
af60: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
af70: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
af80: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
af90: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
afa0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
afb0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
afc0: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
afd0: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
afe0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
aff0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b000: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b010: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b020: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b030: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b040: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b050: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b060: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b070: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b080: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b090: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b0a0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b0b0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b0c0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b0d0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b0e0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b0f0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b100: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b110: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b120: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b130: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b140: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b150: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b160: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b170: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b180: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b190: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b1a0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b1b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b1c0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b1d0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b1e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b1f0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b200: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b210: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b220: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b230: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b240: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
b250: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
b260: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
b270: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
b280: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
b290: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
b2a0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
b2b0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
b2c0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
b2d0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
b2e0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
b2f0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
b300: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
b310: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
b320: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
b330: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
b340: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
b350: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
b360: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
b370: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
b380: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
b390: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
b3a0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
b3b0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
b3c0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
b3d0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
b3e0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
b3f0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
b400: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
b410: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
b420: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
b430: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
b440: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
b450: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
b460: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
b470: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b480: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b490: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
b4a0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
b4b0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
b4c0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b4d0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
b4e0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
b4f0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b500: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b510: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b520: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b530: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b540: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b550: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b560: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b570: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b580: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b590: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b5a0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b5b0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b5c0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b5d0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b5e0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b5f0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b600: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b610: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b620: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b630: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b640: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b650: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b660: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b670: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b680: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b690: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b6a0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b6b0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b6c0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b6d0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b6e0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b6f0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b700: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b710: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b720: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b730: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b740: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b750: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b760: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b770: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b780: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b790: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b7a0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b7b0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b7c0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b7d0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b7e0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b7f0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b800: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b810: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b820: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b830: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b840: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b850: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b860: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b870: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b880: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b890: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b8a0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b8b0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b8c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b8d0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b8e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b8f0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b900: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b910: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b920: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b930: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b940: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b950: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b960: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b970: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b980: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b990: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b9a0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b9b0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b9c0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b9d0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b9e0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b9f0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
ba00: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
ba10: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
ba20: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
ba30: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
ba40: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
ba50: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
ba60: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
ba70: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
ba80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
ba90: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
baa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
bab0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
bac0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
bad0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
bae0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
baf0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
bb00: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
bb10: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
bb20: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
bb30: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
bb40: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
bb50: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
bb60: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
bb70: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
bb80: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
bb90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bba0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bbb0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
bbc0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bbd0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bbe0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
bbf0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
bc00: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
bc10: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
bc20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
bc30: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
bc40: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
bc50: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
bc60: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
bc70: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
bc80: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
bc90: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
bca0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
bcb0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
bcc0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
bcd0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
bce0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bcf0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
bd00: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
bd10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
bd20: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
bd30: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
bd40: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
bd50: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
bd60: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
bd70: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
bd80: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
bd90: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
bda0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
bdb0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
bdc0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
bdd0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
bde0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
bdf0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
be00: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
be10: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
be20: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
be30: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
be40: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
be50: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
be60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
be70: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
be80: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
be90: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
bea0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
beb0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
bec0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
bed0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
bee0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
bef0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
bf00: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
bf10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
bf20: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
bf30: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
bf40: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
bf50: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
bf60: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
bf70: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
bf80: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
bf90: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
bfa0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bfb0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
bfc0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
bfd0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
bfe0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
bff0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
c000: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
c010: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
c020: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c030: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
c040: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
c050: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c060: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
c070: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
c080: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
c090: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
c0a0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
c0b0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
c0c0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
c0d0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
c0e0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c0f0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
c100: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
c110: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
c120: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c130: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
c140: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
c150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c160: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
c170: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
c180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c190: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
c1a0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
c1b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c1c0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
c1d0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
c1e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c1f0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
c200: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
c210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c220: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
c230: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
c240: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c250: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
c260: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
c270: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c280: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
c290: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
c2a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c2b0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
c2c0: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
c2d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
c2e0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
c2f0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
c300: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
c310: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
c320: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
c330: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
c340: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
c350: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
c360: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
c390: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c3a0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
c3b0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
c3c0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c3d0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
c3e0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
c3f0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c400: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
c410: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c420: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
c430: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
c440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c450: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
c460: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
c470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c480: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
c490: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23              27.#
c4a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c4b0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
c4c0: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 0a 2f  TER        28../
c4d0: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
c4e0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
c4f0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
c500: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c510: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
c520: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c530: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
c540: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
c550: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
c560: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
c570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
c580: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c590: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c5a0: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
c5b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c5c0: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
c5d0: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
c5e0: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
c5f0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
c600: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
c610: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
c620: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
c630: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
c640: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c650: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c660: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c670: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c680: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c690: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c6a0: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c6b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c6c0: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c6d0: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c6e0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c6f0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c700: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c710: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c720: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c730: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c740: 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45  3REF: Loadable E
c750: 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a  xtension Thunk.*
c760: 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
c770: 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c  o the opaque sql
c780: 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
c790: 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 70  s structure is p
c7a0: 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
c7b0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
c7c0: 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20  to entry points 
c7d0: 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74  of [loadable ext
c7e0: 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a  ensions].  This.
c7f0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  ** structure mus
c800: 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20 69  t be typedefed i
c810: 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20  n order to work 
c820: 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20  around compiler 
c830: 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73  warnings.** on s
c840: 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  ome platforms..*
c850: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c860: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c870: 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70  tines sqlite3_ap
c880: 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a  i_routines;../*.
c890: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
c8a0: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
c8b0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c8c0: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
c8d0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
c8e0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
c8f0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
c900: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
c910: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
c920: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
c930: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
c940: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
c950: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
c960: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
c970: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
c980: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
c990: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
c9a0: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
c9b0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
c9c0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
c9d0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
c9e0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
c9f0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
ca00: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
ca10: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
ca20: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
ca30: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
ca40: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
ca50: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
ca60: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
ca70: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
ca80: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
ca90: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
caa0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
cab0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
cac0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
cad0: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
cae0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
caf0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
cb00: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
cb10: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
cb20: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
cb30: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
cb40: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
cb50: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
cb60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
cb70: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
cb80: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
cb90: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
cba0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
cbb0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
cbc0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
cbd0: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
cbe0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
cbf0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
cc00: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
cc10: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
cc20: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
cc30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
cc40: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
cc50: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
cc60: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
cc70: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
cc80: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
cc90: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
cca0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
ccb0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
ccc0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
ccd0: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
cce0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
ccf0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
cd00: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
cd10: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
cd20: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
cd30: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
cd40: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
cd50: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
cd60: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
cd70: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
cd80: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
cd90: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
cda0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
cdb0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
cdc0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
cdd0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
cde0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
cdf0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
ce00: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
ce10: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
ce20: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
ce30: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
ce40: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
ce50: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
ce60: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
ce70: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
ce80: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
ce90: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
cea0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
ceb0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
cec0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
ced0: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
cee0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
cef0: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
cf00: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
cf10: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
cf20: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
cf30: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
cf40: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
cf50: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
cf60: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
cf70: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
cf80: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
cf90: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
cfa0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
cfb0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
cfc0: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
cfd0: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
cfe0: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
cff0: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
d000: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
d010: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
d020: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
d030: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
d040: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
d050: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
d060: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
d070: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
d080: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
d090: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
d0a0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
d0b0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
d0c0: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
d0d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
d0e0: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
d0f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
d100: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
d110: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
d120: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
d130: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
d140: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
d150: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
d160: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
d170: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
d180: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
d190: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
d1a0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
d1b0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
d1c0: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
d1d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d1e0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
d1f0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
d200: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
d210: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
d220: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
d230: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d240: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
d250: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d260: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
d270: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
d280: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
d290: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
d2a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
d2b0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
d2c0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
d2d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
d2e0: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
d2f0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
d300: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
d310: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
d320: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
d330: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
d340: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
d350: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
d360: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
d370: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
d380: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
d390: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
d3a0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
d3b0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
d3c0: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
d3d0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
d3e0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d3f0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d400: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
d410: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
d420: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
d430: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
d440: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
d450: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d460: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
d470: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
d480: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
d490: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d4a0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
d4b0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d4c0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
d4d0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d4e0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
d4f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d500: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
d510: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d520: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
d530: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d540: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d550: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
d560: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
d570: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
d580: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
d590: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
d5a0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
d5b0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
d5c0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
d5d0: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
d5e0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
d5f0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
d600: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
d610: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
d620: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
d630: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
d640: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
d650: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
d660: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
d670: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
d680: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
d690: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
d6a0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
d6b0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
d6c0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
d6d0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
d6e0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
d6f0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d700: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
d710: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
d720: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
d730: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
d740: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
d750: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
d760: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
d770: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
d780: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
d790: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d7a0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d7b0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
d7c0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d7d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d7e0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d7f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d800: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
d810: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
d820: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d830: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
d840: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
d850: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
d860: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
d870: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
d880: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d890: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
d8a0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
d8b0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
d8c0: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
d8d0: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
d8e0: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
d8f0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
d900: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
d910: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
d920: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
d930: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
d940: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
d950: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d960: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
d970: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
d980: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
d990: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
d9a0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
d9b0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
d9c0: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
d9d0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d9e0: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
d9f0: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
da00: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
da10: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
da20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
da30: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
da40: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
da50: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
da60: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
da70: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
da80: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
da90: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
daa0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
dab0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
dac0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
dad0: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
dae0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
daf0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
db00: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
db10: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
db20: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
db30: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
db40: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
db50: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
db60: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
db70: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
db80: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
db90: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
dba0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
dbb0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
dbc0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
dbd0: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
dbe0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
dbf0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
dc00: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
dc10: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
dc20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
dc30: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
dc40: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
dc50: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
dc60: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
dc70: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
dc80: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
dc90: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
dca0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
dcb0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
dcc0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
dcd0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
dce0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
dcf0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
dd00: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
dd10: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
dd20: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
dd30: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
dd40: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
dd50: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
dd60: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
dd70: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
dd80: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
dd90: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
dda0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
ddb0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
ddc0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
ddd0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
dde0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
ddf0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
de00: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
de10: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
de20: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
de30: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
de40: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
de50: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
de60: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
de70: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
de80: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
de90: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
dea0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
deb0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
dec0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
ded0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
dee0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
def0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
df00: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
df10: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
df20: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
df30: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
df40: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
df50: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
df60: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
df70: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
df80: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
df90: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
dfa0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
dfb0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
dfc0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
dfd0: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
dfe0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
dff0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
e000: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
e010: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
e020: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
e030: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
e040: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
e050: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
e060: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
e070: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
e080: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
e090: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
e0a0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
e0b0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
e0c0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
e0d0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
e0e0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
e0f0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
e100: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
e110: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
e120: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
e130: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
e140: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
e150: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
e160: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
e170: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
e180: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
e190: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
e1a0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
e1b0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
e1c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
e1d0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
e1e0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
e1f0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
e200: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
e210: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
e220: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
e230: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
e240: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
e250: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
e260: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e270: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
e280: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
e290: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
e2a0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
e2b0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
e2c0: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
e2d0: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
e2e0: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
e2f0: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
e300: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
e310: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e320: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
e330: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
e340: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
e350: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
e360: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
e370: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
e380: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
e390: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
e3a0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
e3b0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
e3c0: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
e3d0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
e3e0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e3f0: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
e400: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
e410: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
e420: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
e430: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
e440: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
e450: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
e460: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
e470: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
e480: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
e490: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
e4a0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
e4b0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
e4c0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
e4d0: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
e4e0: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
e4f0: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
e500: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
e510: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
e520: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
e530: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
e540: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
e550: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
e560: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
e570: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
e580: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
e590: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
e5a0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
e5b0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
e5c0: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
e5d0: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
e5e0: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
e5f0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
e600: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
e610: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
e620: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
e630: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e640: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
e650: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
e660: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
e670: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
e680: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
e690: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
e6a0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
e6b0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
e6c0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e6d0: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
e6e0: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
e6f0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
e700: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
e710: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
e720: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
e730: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e740: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
e750: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
e760: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
e770: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
e780: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
e790: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
e7a0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
e7b0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
e7c0: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
e7d0: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
e7e0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
e7f0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
e800: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
e810: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
e820: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
e830: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
e840: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
e850: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
e860: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
e870: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
e880: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
e890: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
e8a0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
e8b0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
e8c0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
e8d0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
e8e0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e8f0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
e900: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
e910: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
e920: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
e930: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e940: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
e950: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
e960: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
e970: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
e980: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
e990: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
e9a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e9b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
e9c0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
e9d0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
e9e0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e9f0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
ea00: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
ea10: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
ea20: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
ea30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ea40: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
ea50: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
ea60: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
ea70: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
ea80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ea90: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
eaa0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
eab0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
eac0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
ead0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
eae0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
eaf0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
eb00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
eb10: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
eb20: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
eb30: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
eb40: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
eb50: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
eb60: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
eb70: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
eb80: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
eb90: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
eba0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
ebb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
ebc0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
ebd0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
ebe0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
ebf0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
ec00: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
ec10: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
ec20: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
ec30: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
ec40: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
ec50: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
ec60: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
ec70: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
ec80: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
ec90: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
eca0: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
ecb0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
ecc0: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
ecd0: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
ece0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
ecf0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
ed00: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
ed10: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
ed20: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
ed30: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
ed40: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
ed50: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
ed60: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
ed70: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
ed80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
ed90: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
eda0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
edb0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
edc0: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
edd0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
ede0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
edf0: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
ee00: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
ee10: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ee20: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ee30: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
ee40: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ee50: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
ee60: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
ee70: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
ee80: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ee90: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
eea0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
eeb0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  future versions.
eec0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
eed0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
eee0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
eef0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
ef00: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
ef10: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ef20: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
ef30: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
ef40: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
ef50: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
ef60: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
ef70: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
ef80: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
ef90: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
efa0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
efb0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
efc0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
efd0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
efe0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
eff0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
f000: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f010: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
f020: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f030: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
f040: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
f050: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
f060: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
f070: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
f080: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f090: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
f0a0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
f0b0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
f0c0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
f0d0: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
f0e0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
f0f0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
f100: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
f110: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
f120: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
f130: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
f140: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
f150: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
f160: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
f170: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
f180: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
f190: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
f1a0: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
f1b0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
f1c0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
f1d0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
f1e0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
f1f0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f200: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
f210: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
f220: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
f230: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
f240: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
f250: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
f260: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
f270: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
f280: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
f290: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
f2a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f2b0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
f2c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f2d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
f2e0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
f2f0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
f300: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
f310: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f320: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
f330: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
f340: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
f350: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
f360: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
f370: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f380: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
f390: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
f3a0: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
f3b0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
f3c0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
f3d0: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
f3e0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
f3f0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
f400: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
f410: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
f420: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
f430: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
f440: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f450: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f460: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f470: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f480: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f490: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f4a0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
f4b0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f4c0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f4d0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
f4e0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f4f0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
f500: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f510: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
f520: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
f530: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
f540: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
f550: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
f560: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
f570: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
f580: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
f590: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f5a0: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
f5b0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
f5c0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
f5d0: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
f5e0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
f5f0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
f600: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
f610: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
f620: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
f630: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f640: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
f650: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
f660: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
f670: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f680: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f690: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
f6a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f6b0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
f6c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
f6d0: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
f6e0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
f6f0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
f700: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f710: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
f720: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
f730: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
f740: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
f750: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
f760: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f770: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
f780: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
f790: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
f7a0: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
f7b0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
f7c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f7d0: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
f7e0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f7f0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
f800: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f810: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f820: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f830: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
f840: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
f850: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
f860: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f870: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
f880: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
f890: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
f8a0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
f8b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f8c0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
f8d0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
f8e0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
f8f0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
f900: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
f910: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
f920: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
f930: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
f940: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
f950: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
f960: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
f970: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
f980: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
f990: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f9a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f9b0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
f9c0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
f9d0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
f9e0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
f9f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
fa00: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
fa10: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
fa20: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
fa30: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
fa40: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
fa50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fa60: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
fa70: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
fa80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fa90: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
faa0: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
fab0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
fac0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
fad0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
fae0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
faf0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
fb00: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
fb10: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
fb20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
fb30: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
fb40: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
fb50: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
fb60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
fb70: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
fb80: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
fb90: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
fba0: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
fbb0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
fbc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
fbd0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
fbe0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
fbf0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
fc00: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
fc10: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
fc20: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
fc30: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fc40: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fc50: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
fc60: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
fc70: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
fc80: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
fc90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fca0: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
fcb0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
fcc0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
fcd0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
fce0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
fcf0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
fd00: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
fd10: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
fd20: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
fd30: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
fd40: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
fd50: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
fd60: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
fd70: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
fd80: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
fd90: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
fda0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
fdb0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
fdc0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
fdd0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
fde0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
fdf0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
fe00: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fe10: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fe20: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
fe30: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
fe40: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
fe50: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
fe60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fe70: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
fe80: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
fe90: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
fea0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
feb0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
fec0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
fed0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
fee0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
fef0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
ff00: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
ff10: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
ff20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ff30: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
ff40: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
ff50: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
ff60: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
ff70: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
ff80: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
ff90: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
ffa0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
ffb0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ffc0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
ffd0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
ffe0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
fff0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
10000 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
10010 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
10020 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
10030 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
10040 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
10050 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
10060 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
10070 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
10080 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
10090 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
100a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
100b0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
100c0 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
100d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
100e0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
100f0 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
10100 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10110 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
10120 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
10130 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
10140 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
10150 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
10160 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
10170 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
10180 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
10190 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
101a0 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
101b0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
101c0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
101d0 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
101e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
101f0 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
10200 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
10210 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
10220 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
10230 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
10240 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
10250 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
10260 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
10270 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
10280 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
10290 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
102a0 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
102b0 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
102c0 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
102d0 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
102e0 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
102f0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
10300 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10310 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
10320 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
10330 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
10340 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
10350 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
10360 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
10370 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10380 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
10390 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
103a0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
103b0 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
103c0 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
103d0 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
103e0 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
103f0 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
10400 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
10410 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
10420 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
10430 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
10440 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
10450 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
10460 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
10470 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
10480 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
10490 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
104a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
104b0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
104c0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
104d0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
104e0 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
104f0 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
10500 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
10510 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
10520 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
10530 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
10540 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10550 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
10560 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
10570 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10580 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
10590 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
105a0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
105b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
105c0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
105d0 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
105e0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
105f0 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
10600 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
10610 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
10620 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
10630 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
10640 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
10650 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
10660 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
10670 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
10680 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
10690 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
106a0 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
106b0 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
106c0 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
106d0 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
106e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
106f0 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
10700 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
10710 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
10720 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10730 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
10740 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
10750 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
10760 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
10770 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
10780 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
10790 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
107a0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
107b0 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
107c0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
107d0 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
107e0 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
107f0 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
10800 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lure..*/.SQLITE_
10810 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
10820 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69  TDCALL sqlite3_i
10830 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
10840 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10850 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
10860 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10870 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
10880 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
10890 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f  CALL sqlite3_os_
108a0 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
108b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
108c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
108d0 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
108e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
108f0 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
10900 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
10910 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10920 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10930 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10940 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
10950 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10960 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
10970 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
10980 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
10990 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
109a0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
109b0 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
109c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
109d0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
109e0 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
109f0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
10a00 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
10a10 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
10a20 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
10a30 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
10a40 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
10a50 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
10a60 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c  l needs..**.** <
10a70 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  b>The sqlite3_co
10a80 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10a90 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10aa0 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74  fe. The applicat
10ab0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
10ac0 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
10ad0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10ae0 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
10af0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
10b00 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
10b10 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
10b20 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ning.</b>.**.** 
10b30 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10b40 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ig() interface.*
10b50 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
10b60 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
10b70 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
10b80 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
10b90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10ba0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
10bb0 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
10bc0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
10bd0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
10be0 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
10bf0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
10c00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10c10 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
10c20 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10c30 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10c40 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
10c50 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
10c60 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
10c70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
10c80 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
10c90 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
10ca0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10cb0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10cc0 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
10cd0 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
10ce0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10cf0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
10d00 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
10d10 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
10d20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10d30 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10d40 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
10d50 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
10d60 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
10d70 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
10d80 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
10d90 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10da0 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10db0 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
10dc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
10de0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10df0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
10e00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
10e10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10e20 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
10e30 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10e40 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
10e50 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
10e60 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
10e70 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
10e80 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
10e90 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
10ea0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
10eb0 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
10ec0 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
10ed0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10ee0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10f00 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
10f10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
10f20 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
10f30 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10f40 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
10f50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10f60 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10f70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10f80 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10f90 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
10fa0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10fb0 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
10fc0 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10fd0 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10fe0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10ff0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
11000 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
11010 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
11020 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
11030 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11040 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
11050 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
11060 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
11070 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
11080 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11090 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
110a0 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
110b0 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
110c0 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
110d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
110e0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
110f0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
11100 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
11110 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11120 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11130 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
11140 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
11150 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
11160 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
11170 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
11180 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
11190 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
111a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
111b0 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  nt SQLITE_CDECL 
111c0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
111d0 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
111e0 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
111f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
11200 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
11210 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
11220 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11230 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
11240 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
11250 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
11260 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
11270 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11280 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
11290 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
112a0 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
112b0 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
112c0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
112d0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
112e0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
112f0 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
11300 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
11310 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11320 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
11330 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11340 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
11350 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
11360 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11370 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
11380 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
11390 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
113a0 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
113b0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
113c0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
113d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
113e0 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
113f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
11400 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
11410 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
11420 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
11430 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
11440 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
11450 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
11460 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
11470 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
11480 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
11490 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
114a0 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
114b0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
114c0 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
114d0 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
114e0 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
114f0 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
11500 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
11510 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
11520 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
11530 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
11540 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
11550 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11560 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
11570 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11580 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
11590 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
115a0 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
115b0 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
115c0 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
115d0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
115e0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
115f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11600 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
11610 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
11620 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
11630 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
11640 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
11650 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
11660 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
11670 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
11680 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
11690 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
116a0 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
116b0 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
116c0 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
116d0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
116e0 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
116f0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
11700 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
11710 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
11720 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
11730 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
11740 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
11750 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
11760 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
11770 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
11780 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
11790 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
117a0 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
117b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
117c0 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
117d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
117e0 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
117f0 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
11800 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
11810 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
11820 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
11830 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
11840 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
11850 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
11860 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
11870 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
11880 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11890 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
118a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
118b0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
118c0 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
118d0 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
118e0 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
118f0 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
11900 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
11910 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
11920 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
11930 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
11940 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
11950 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
11960 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
11970 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
11980 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
11990 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
119a0 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
119b0 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
119c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
119d0 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
119e0 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
119f0 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
11a00 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
11a10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
11a20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11a30 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
11a40 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
11a50 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
11a60 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11a70 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
11a80 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
11a90 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
11aa0 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
11ab0 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
11ac0 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
11ad0 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
11ae0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11af0 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
11b00 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
11b10 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11b20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
11b30 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
11b40 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
11b50 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
11b60 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
11b70 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
11b80 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
11b90 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
11ba0 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
11bb0 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
11bc0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11bd0 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
11be0 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
11bf0 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
11c00 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
11c10 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
11c20 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
11c30 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
11c40 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11c50 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
11c60 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11c70 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
11c80 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
11c90 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
11ca0 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
11cb0 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
11cc0 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
11cd0 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11ce0 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
11cf0 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
11d00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11d10 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
11d20 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11d30 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
11d40 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
11d50 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
11d60 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
11d70 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
11d80 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
11d90 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
11da0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11db0 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
11dc0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
11dd0 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
11de0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
11df0 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
11e00 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
11e10 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
11e20 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
11e30 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11e40 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
11e50 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
11e60 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
11e70 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
11e80 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
11e90 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11ea0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11eb0 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
11ec0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
11ed0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11ee0 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
11ef0 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
11f00 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
11f10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
11f20 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
11f30 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
11f40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
11f50 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
11f60 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
11f70 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
11f80 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
11f90 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
11fa0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
11fb0 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11fc0 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
11fd0 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
11fe0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11ff0 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
12000 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
12010 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
12020 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
12030 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
12040 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
12050 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
12060 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
12070 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
12080 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
12090 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
120a0 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
120b0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
120c0 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
120d0 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
120e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
120f0 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
12100 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
12110 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
12120 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
12130 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
12140 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
12150 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12160 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
12170 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
12180 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
12190 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
121a0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
121b0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
121c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
121d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
121e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
121f0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
12200 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
12210 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
12220 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
12230 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
12240 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
12250 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
12260 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
12270 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
12280 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
12290 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
122a0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
122b0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
122c0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
122d0 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
122e0 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
122f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12300 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
12310 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
12320 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
12330 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
12340 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
12350 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
12360 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
12370 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
12380 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
12390 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
123a0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
123b0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
123c0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
123d0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
123e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
123f0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
12400 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
12410 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
12420 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
12430 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
12440 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
12450 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
12460 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
12470 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
12480 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
12490 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
124a0 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
124b0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
124c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
124d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
124e0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
124f0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
12500 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12510 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
12520 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
12530 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
12540 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
12550 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
12560 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
12570 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
12580 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12590 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
125a0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
125b0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
125c0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
125d0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
125e0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
125f0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
12600 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12610 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
12620 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12630 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
12640 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12650 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12660 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12670 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12680 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12690 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
126a0 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
126b0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
126c0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
126d0 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
126e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
126f0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12700 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
12710 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
12720 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
12730 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
12740 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
12750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12760 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
12770 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
12780 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
12790 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
127a0 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
127b0 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
127c0 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
127d0 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
127e0 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
127f0 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
12800 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
12810 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
12820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12830 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
12840 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
12850 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12860 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12870 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12880 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12890 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
128a0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
128b0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
128c0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
128d0 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
128e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
128f0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12900 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12910 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12920 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
12930 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12940 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12950 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
12960 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12970 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12980 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
12990 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
129a0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
129b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
129c0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
129d0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
129e0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
129f0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
12a00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
12a10 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
12a20 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
12a30 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
12a40 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
12a50 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
12a60 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
12a70 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
12a80 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
12a90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12aa0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
12ab0 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
12ac0 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
12ad0 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
12ae0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12af0 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
12b00 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
12b10 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
12b20 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
12b30 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
12b40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12b50 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
12b70 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
12b80 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
12b90 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
12ba0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
12bb0 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
12bc0 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
12bd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
12be0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
12bf0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
12c00 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
12c10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12c20 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12c30 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12c40 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12c50 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12c60 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12c70 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12c80 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
12c90 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
12ca0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12cb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12cc0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12cd0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12ce0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12cf0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
12d00 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
12d10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12d20 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12d40 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12d50 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12d60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12d70 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12d80 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  G_MALLOC option 
12d90 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12da0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12db0 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
12dc0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12dd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12de0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12df0 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
12e00 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12e10 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12e20 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12e30 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12e40 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
12e50 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
12e60 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12e70 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
12e80 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
12e90 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
12ea0 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
12eb0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
12ec0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
12ed0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ee0 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
12ef0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
12f00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
12f10 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
12f20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12f30 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12f40 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12f50 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
12f60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12f70 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12f80 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  _GETMALLOC optio
12f90 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12fa0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
12fb0 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
12fc0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12fd0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12fe0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12ff0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73  cture..** The [s
13000 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13010 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
13020 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
13030 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
13040 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
13050 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
13060 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13070 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13080 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13090 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
130a0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
130b0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
130c0 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
130d0 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
130e0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
130f0 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
13100 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
13110 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
13120 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13130 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
13140 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13150 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
13160 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
13170 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13180 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65  ATUS option take
13190 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
131a0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a  t of type int,.*
131b0 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  * interpreted as
131c0 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
131d0 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
131e0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
131f0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72  tion of.** memor
13200 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13210 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
13220 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13230 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
13240 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68  .** disabled, th
13250 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
13260 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
13270 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
13280 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
13290 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
132a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
132b0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
132c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
132d0 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
132e0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
132f0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
13300 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
13310 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a  te3_status64()].
13320 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
13330 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
13340 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13350 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
13360 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
13370 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
13380 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
13390 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
133a0 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
133b0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
133c0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
133d0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
133e0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
133f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13400 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13410 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
13420 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
13430 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13440 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13450 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65  RATCH option spe
13460 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13470 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
13480 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13490 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68   use for scratch
134a0 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72   memory.  ^(Ther
134b0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
134c0 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49  ments.** to SQLI
134d0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
134e0 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  H:  A pointer an
134f0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
13500 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
13510 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
13520 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
13530 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
13540 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
13550 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
13560 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
13570 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
13580 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
13590 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
135a0 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66   (N).)^.** The f
135b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
135c0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
135d0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
135e0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
135f0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13600 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
13610 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13620 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68   not use more th
13630 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
13640 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
13650 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13660 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74  ll never request
13670 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
13680 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
13690 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
136a0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
136b0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   size..** ^If SQ
136c0 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
136d0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
136e0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
136f0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13700 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
13710 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13720 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
13730 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13740 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
13750 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
13760 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20  y needed.<p>.** 
13770 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63  ^When the applic
13780 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61  ation provides a
13790 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72  ny amount of scr
137a0 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e  atch memory usin
137b0 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  g.** SQLITE_CONF
137c0 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69  IG_SCRATCH, SQLi
137d0 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65  te avoids unnece
137e0 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b  ssary large.** [
137f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68  sqlite3_malloc|h
13800 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d  eap allocations]
13810 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65  ..** This can he
13820 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66  lp [Robson proof
13830 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20  |prevent memory 
13840 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
13850 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70  res] due to heap
13860 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  .** fragmentatio
13870 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20  n in low-memory 
13880 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
13890 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
138a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
138b0 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
138c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
138d0 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
138e0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
138f0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13900 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
13910 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
13920 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
13930 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
13940 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
13950 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
13960 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
13970 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13980 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13990 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
139a0 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
139b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
139c0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
139d0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
139e0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
139f0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
13a00 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
13a10 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
13a20 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
13a30 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13a40 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
13a50 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
13a60 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
13a70 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
13a80 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
13a90 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
13aa0 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
13ab0 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
13ac0 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
13ad0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
13ae0 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
13af0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
13b00 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
13b10 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
13b20 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
13b30 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
13b40 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
13b50 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
13b60 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
13b70 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
13b80 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
13b90 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
13ba0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
13bb0 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
13bc0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
13bd0 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
13be0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
13bf0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
13c00 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
13c10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
13c20 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
13c30 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
13c40 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
13c50 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
13c60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
13c70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13c80 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
13c90 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
13ca0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13cb0 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
13cc0 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
13cd0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
13ce0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
13cf0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
13d00 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
13d10 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
13d20 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
13d30 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
13d40 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
13d50 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
13d60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13d70 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
13d80 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
13d90 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
13da0 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
13db0 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
13dc0 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
13dd0 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
13de0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
13df0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
13e00 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
13e10 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
13e20 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
13e30 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
13e40 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
13e50 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
13e60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
13e70 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
13e80 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
13e90 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
13ea0 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
13eb0 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
13ec0 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
13ed0 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13ee0 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13ef0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13f00 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13f10 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
13f20 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
13f30 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
13f40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13f50 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
13f60 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
13f70 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
13f80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13f90 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
13fa0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13fb0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13fc0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13fd0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
13fe0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13ff0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
14000 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
14010 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
14020 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
14030 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
14040 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
14050 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
14060 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
14070 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14080 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  CH] and.** [SQLI
14090 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
140a0 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
140b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
140c0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
140d0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
140e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
140f0 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
14100 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
14110 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
14120 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
14130 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
14140 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
14150 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
14160 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
14170 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14180 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
14190 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
141a0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
141b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
141c0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
141d0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
141e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
141f0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
14200 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14210 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
14220 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
14230 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
14240 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
14250 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
14260 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
14270 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
14280 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
14290 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
142a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
142b0 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
142c0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
142d0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
142e0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
142f0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
14300 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
14310 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
14320 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
14330 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
14340 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
14350 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
14360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14370 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
14380 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14390 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
143a0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
143b0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
143c0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
143d0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
143e0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
143f0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
14400 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
14410 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
14420 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
14430 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
14440 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
14450 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14460 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
14470 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
14480 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14490 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
144a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
144b0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
144c0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
144d0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
144e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
144f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14500 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
14510 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
14520 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
14530 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14540 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14550 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
14560 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
14570 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
14580 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
14590 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
145a0 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
145b0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
145c0 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
145d0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
145e0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
145f0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
14600 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14610 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
14620 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
14630 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14640 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
14650 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14660 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14670 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14680 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14690 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
146a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
146b0 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
146c0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
146d0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
146e0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
146f0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
14700 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14710 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
14720 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14730 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14740 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14750 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14760 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14770 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14780 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
14790 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
147a0 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
147b0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
147c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
147d0 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
147e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
147f0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
14800 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14810 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
14820 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
14830 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14840 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
14850 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14860 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14870 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14880 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14890 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
148a0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
148b0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
148c0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
148d0 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
148e0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
148f0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
14900 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
14910 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
14920 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
14930 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
14940 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
14950 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
14960 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14970 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14980 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14990 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
149a0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
149b0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
149c0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
149d0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
149e0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
149f0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
14a00 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
14a10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14a20 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14a30 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14a40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14a50 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14a60 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14a70 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14a80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14a90 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
14aa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14ab0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
14ac0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14ad0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14ae0 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
14af0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
14b00 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
14b10 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
14b20 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
14b30 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
14b40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14b50 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
14b60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14b70 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14b80 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14b90 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
14ba0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
14bb0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
14bc0 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
14bd0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
14be0 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
14bf0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14c00 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
14c10 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
14c20 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
14c30 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
14c40 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
14c50 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
14c60 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14c70 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
14c80 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
14c90 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
14ca0 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
14cb0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
14cc0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14cd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14ce0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
14cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14d00 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14d10 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14d20 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
14d30 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14d40 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14d50 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14d60 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14d70 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14d80 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
14d90 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
14da0 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
14db0 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
14dc0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14dd0 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
14de0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14df0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
14e00 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14e10 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
14e20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14e30 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14e40 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14e50 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14e60 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14e70 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14e80 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
14e90 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14ea0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14eb0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14ec0 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14ed0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14ee0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
14ef0 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
14f00 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
14f10 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14f20 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
14f30 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
14f40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f50 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
14f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14f70 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
14f80 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14f90 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
14fa0 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
14fb0 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
14fc0 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
14fd0 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
14fe0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14ff0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
15000 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
15010 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
15020 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
15030 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
15040 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
15050 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
15060 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
15070 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
15080 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
15090 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
150a0 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
150b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
150c0 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
150d0 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
150e0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
150f0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
15100 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
15110 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
15120 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
15130 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
15140 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
15150 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
15160 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
15170 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
15180 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
15190 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
151a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
151b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
151c0 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
151d0 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
151e0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
151f0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
15200 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15210 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
15220 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
15230 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
15240 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15250 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
15260 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
15270 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
15280 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
15290 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
152a0 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
152b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
152c0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
152d0 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
152e0 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
152f0 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
15300 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
15310 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
15320 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
15330 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
15340 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
15350 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
15360 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
15370 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
15380 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15390 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
153a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
153b0 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
153c0 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
153d0 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
153e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
153f0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
15400 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
15410 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
15420 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15430 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
15440 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
15450 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
15460 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
15470 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15480 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
15490 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
154a0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
154b0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
154c0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
154d0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
154e0 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
154f0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
15500 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
15510 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
15520 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15530 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
15540 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
15550 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
15560 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
15570 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
15580 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
15590 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
155a0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
155b0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
155c0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
155d0 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
155e0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
155f0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
15600 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
15610 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
15620 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
15630 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
15640 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
15650 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
15660 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
15670 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
15680 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
15690 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
156a0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
156b0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
156c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
156d0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
156e0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
156f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
15700 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
15710 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
15720 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
15730 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
15740 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15750 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
15760 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
15770 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15780 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15790 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
157a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
157b0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
157c0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
157d0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
157e0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
157f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15800 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
15810 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15820 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
15830 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
15840 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
15850 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
15860 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
15870 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
15880 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
15890 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
158a0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
158b0 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
158c0 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
158d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
158e0 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
158f0 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
15900 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
15910 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
15920 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
15930 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
15940 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
15950 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
15960 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15970 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15980 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
15990 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
159a0 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
159b0 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
159c0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
159d0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
159e0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
159f0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
15a00 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
15a10 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
15a20 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
15a30 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
15a40 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
15a50 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
15a60 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
15a70 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
15a80 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
15a90 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
15aa0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15ab0 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
15ac0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15ad0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
15ae0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15af0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
15b00 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
15b10 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
15b20 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
15b30 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
15b40 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
15b50 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
15b60 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
15b70 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15b80 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
15b90 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
15ba0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15bb0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
15bc0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15bd0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
15be0 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
15bf0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15c00 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
15c10 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
15c20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
15c30 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
15c40 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15c50 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
15c60 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
15c70 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
15c80 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
15c90 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
15ca0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
15cb0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
15cc0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15cd0 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
15ce0 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
15cf0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15d00 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
15d10 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
15d20 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
15d30 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
15d40 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
15d50 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
15d60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
15d70 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
15d80 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
15d90 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15da0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
15db0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15dc0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
15dd0 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
15de0 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
15df0 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
15e00 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
15e10 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
15e20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
15e30 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
15e40 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15e50 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
15e60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15e70 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
15e80 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
15e90 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
15ea0 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
15eb0 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
15ec0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15ed0 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
15ee0 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
15ef0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15f00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15f10 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
15f20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
15f30 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
15f40 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
15f50 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
15f60 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
15f70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15f80 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
15f90 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
15fa0 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
15fb0 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
15fc0 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
15fd0 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
15fe0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15ff0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
16000 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
16010 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16020 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
16030 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16040 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
16050 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
16060 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
16070 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
16080 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
16090 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
160a0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
160b0 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
160c0 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
160d0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
160e0 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
160f0 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
16100 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
16110 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
16120 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
16130 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
16140 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
16150 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
16160 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
16170 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
16180 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
16190 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
161a0 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
161b0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
161c0 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
161d0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
161e0 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
161f0 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
16200 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
16210 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
16220 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
16230 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
16240 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
16250 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
16260 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
16270 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
16280 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
16290 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
162a0 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
162b0 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
162c0 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
162d0 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
162e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
162f0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16300 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
16310 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16320 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
16330 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
16340 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16350 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
16360 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
16370 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
16380 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
16390 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
163a0 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
163b0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
163c0 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
163d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
163e0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
163f0 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
16400 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
16410 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
16420 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
16430 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
16440 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
16450 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16460 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
16470 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16480 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16490 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
164a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
164b0 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
164c0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
164d0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
164e0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
164f0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
16500 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
16510 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
16520 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
16530 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
16540 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
16550 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
16560 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16570 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
16580 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
16590 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
165a0 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
165b0 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
165c0 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
165d0 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
165e0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
165f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16600 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
16610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16620 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
16630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16640 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
16650 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16660 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
16670 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16680 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
16690 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
166a0 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
166b0 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
166c0 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
166d0 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
166e0 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
166f0 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
16700 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
16710 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
16720 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
16730 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
16740 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
16750 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
16760 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
16770 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
16780 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
16790 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
167a0 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
167b0 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
167c0 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
167d0 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
167e0 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
167f0 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
16800 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
16810 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
16820 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
16830 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a   this value..**.
16840 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16850 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16860 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
16870 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16880 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e  L_SPILL.** <dd>^
16890 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
168a0 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
168b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
168c0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
168d0 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65   which.** become
168e0 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74  s the [statement
168f0 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d   journal] spill-
16900 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c  to-disk threshol
16910 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65  d.  .** [Stateme
16920 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65  nt journals] are
16930 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
16940 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65  until their size
16950 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65   (in bytes).** e
16960 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65  xceeds this thre
16970 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20  shold, at which 
16980 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77  point they are w
16990 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a  ritten to disk..
169a0 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72  ** Or if the thr
169b0 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74  eshold is -1, st
169c0 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
169d0 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64   are always held
169e0 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20  .** exclusively 
169f0 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69  in memory..** Si
16a00 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65  nce many stateme
16a10 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65  nt journals neve
16a20 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20  r become large, 
16a30 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c  setting the spil
16a40 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74  l.** threshold t
16a50 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61  o a value such a
16a60 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61  s 64KiB can grea
16a70 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61  tly reduce the a
16a80 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20  mount of.** I/O 
16a90 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70  required to supp
16aa0 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f  ort statement ro
16ab0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64  llback..** The d
16ac0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
16ad0 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
16ae0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74   controlled by t
16af0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54  he.** [SQLITE_ST
16b00 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f  MTJRNL_SPILL] co
16b10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16b20 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
16b30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16b40 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
16b50 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
16b60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16b70 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
16b80 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
16b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ba0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
16bb0 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
16bc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16bd0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
16be0 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
16bf0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16c00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16c10 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
16c20 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
16c30 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16c40 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
16c60 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
16c70 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16c80 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16c90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16ca0 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
16cb0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16cc0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16cd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16ce0 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
16cf0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
16d00 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
16d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d20 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
16d30 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
16d40 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
16d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16d60 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
16d70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16d80 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16da0 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
16db0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16dc0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
16dd0 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
16de0 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
16df0 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
16e00 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
16e10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16e20 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16e30 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
16e40 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16e50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16e60 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
16e70 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
16e80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16e90 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
16ea0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16eb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16ec0 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
16ed0 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
16ee0 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
16ef0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16f00 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
16f10 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16f20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16f30 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
16f40 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16f50 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
16f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16f70 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
16f80 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
16f90 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
16fa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16fb0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16fc0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
16fd0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
16fe0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16ff0 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
17000 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
17010 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
17020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
17030 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
17040 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
17050 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
17060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17070 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
17080 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
17090 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
170a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
170b0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
170c0 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
170d0 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
170e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
170f0 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
17100 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
17110 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
17120 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17130 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
17140 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
17150 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
17160 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17170 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
17180 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
17190 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
171a0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
171b0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
171c0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
171d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
171e0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
171f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
17200 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
17210 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
17220 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
17230 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
17240 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
17250 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
17260 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
17270 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
17280 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
17290 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
172a0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
172b0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
172c0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
172d0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
172e0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
172f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17300 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
17310 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
17320 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
17330 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17340 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
17350 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
17360 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
17370 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
17380 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
17390 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
173a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
173b0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
173c0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
173d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
173e0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
173f0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17400 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
17410 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17420 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
17430 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
17440 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
17450 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
17460 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
17470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17480 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
17490 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
174a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
174b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
174c0 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
174d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
174e0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
174f0 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
17500 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
17510 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17520 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
17530 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17540 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
17550 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
17560 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
17570 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
17580 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
17590 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
175a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
175b0 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
175c0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
175d0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
175e0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
175f0 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
17600 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
17610 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
17620 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
17630 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
17640 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
17650 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
17660 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
17670 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
17680 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
17690 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
176a0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
176b0 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
176c0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
176d0 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
176e0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
176f0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
17700 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
17710 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
17720 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
17730 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
17740 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
17750 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
17760 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
17770 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
17780 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
17790 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
177a0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
177b0 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
177c0 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
177d0 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
177e0 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
177f0 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
17800 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
17810 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
17820 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
17830 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
17840 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
17850 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
17860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17870 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
17880 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
17890 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
178a0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
178b0 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
178c0 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
178d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
178e0 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
178f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
17900 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
17910 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
17920 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
17930 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17940 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17950 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
17960 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17970 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17980 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
17990 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
179a0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
179b0 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
179c0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
179d0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
179e0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
179f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17a00 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
17a10 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
17a20 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
17a30 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
17a40 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
17a50 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
17a60 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
17a70 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
17a80 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
17a90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17aa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17ab0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17ac0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17ad0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17ae0 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
17af0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
17b00 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
17b10 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
17b20 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17b30 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
17b40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
17b50 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
17b60 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
17b70 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
17b80 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17b90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17ba0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17bb0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17bc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17bd0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17be0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17bf0 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
17c00 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
17c10 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
17c20 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17c30 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17c40 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17c50 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17c60 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17c70 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
17c80 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
17c90 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
17ca0 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17cb0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17cc0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17cd0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17ce0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17cf0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
17d00 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
17d10 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
17d20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
17d30 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
17d40 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
17d50 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17d60 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17d70 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17d80 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17d90 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17da0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17db0 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17dc0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17dd0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17de0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17df0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17e00 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
17e10 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17e20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17e30 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17e40 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75  ble the two-argu
17e50 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ment.** version 
17e60 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b  of the [fts3_tok
17e70 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69  enizer()] functi
17e80 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74  on which is part
17e90 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33   of the.** [FTS3
17ea0 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72  ] full-text sear
17eb0 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73  ch engine extens
17ec0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ion..** There sh
17ed0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17ee0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17ef0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17f00 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17f10 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17f20 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33   to disable fts3
17f30 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a  _tokenizer() or.
17f40 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17f50 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  nable fts3_token
17f60 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69  izer() or negati
17f70 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17f80 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
17f90 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
17fa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17fb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17fc0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17fd0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17fe0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17ff0 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73  cate whether fts
18000 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64  3_tokenizer is d
18010 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18020 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
18030 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
18040 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18050 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
18060 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
18070 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
18080 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
18090 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
180a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
180b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
180c0 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
180d0 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SION</dt>.** <dd
180e0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
180f0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
18100 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
18110 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
18120 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e  tension()].** in
18130 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64  terface independ
18140 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f  ently of the [lo
18150 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
18160 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
18170 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e   The [sqlite3_en
18180 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
18190 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c  ion()] API enabl
181a0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62  es or disables b
181b0 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  oth the.** C-API
181c0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
181d0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20  xtension()] and 
181e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
181f0 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
18200 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ()]..** There sh
18210 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
18220 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18230 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69  ..** When the fi
18240 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
18250 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
18260 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74  s 1, then only t
18270 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65  he C-API is.** e
18280 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53  nabled and the S
18290 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61  QL function rema
182a0 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49  ins disabled.  I
182b0 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  f the first argu
182c0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ment to.** this 
182d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20  interface is 0, 
182e0 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d  then both the C-
182f0 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20  API and the SQL 
18300 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73  function are dis
18310 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  abled..** If the
18320 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18330 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63  is -1, then no c
18340 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20  hanges are made 
18350 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68  to state of eith
18360 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20  er the.** C-API 
18370 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  or the SQL funct
18380 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ion..** The seco
18390 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
183a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
183b0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
183c0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
183d0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
183e0 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c  ate whether [sql
183f0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18400 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ion()] interface
18410 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20  .** is disabled 
18420 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f  or enabled follo
18430 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18440 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18450 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20  meter may.** be 
18460 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
18470 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
18480 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73  e new setting is
18490 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
184a0 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ck..** </dd>.**.
184b0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
184c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
184d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
184e0 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f            1001 /
184f0 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
18500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18510 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18520 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20  E_FKEY          
18530 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74   1002 /* int int
18540 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18550 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18560 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  BLE_TRIGGER     
18570 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69     1003 /* int i
18580 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18590 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
185a0 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
185b0 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74  IZER 1004 /* int
185c0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
185d0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
185e0 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
185f0 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69  ENSION 1005 /* i
18600 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
18610 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
18620 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
18630 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
18640 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
18650 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
18660 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
18670 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
18680 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
18690 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
186a0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
186b0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
186c0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
186d0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
186e0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
186f0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
18700 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
18710 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
18720 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ity..*/.SQLITE_A
18730 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
18740 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78  DCALL sqlite3_ex
18750 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
18760 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
18770 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
18780 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
18790 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
187a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
187b0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
187c0 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
187d0 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
187e0 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
187f0 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
18800 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
18810 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
18820 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
18830 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
18840 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
18850 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
18860 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
18870 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
18880 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
18890 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
188a0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
188b0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
188c0 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
188d0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
188e0 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
188f0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
18900 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
18910 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
18920 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
18930 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
18940 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
18950 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
18960 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
18970 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
18980 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
18990 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
189a0 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20  of the .** most 
189b0 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
189c0 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
189d0 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
189e0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
189f0 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
18a00 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
18a10 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
18a20 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
18a30 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65  ables are not re
18a40 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e  corded..** ^If n
18a50 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
18a60 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
18a70 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65  d tables.** have
18a80 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
18a90 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
18aa0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a  onnection D, .**
18ab0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
18ac0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
18ad0 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  D) returns zero.
18ae0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
18af0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
18b00 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
18b10 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
18b20 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
18b30 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
18b40 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
18b50 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
18b60 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
18b70 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
18b80 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
18b90 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
18ba0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
18bb0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
18bc0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
18bd0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
18be0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
18bf0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
18c00 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
18c10 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
18c20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
18c30 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
18c40 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
18c50 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
18c60 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
18c70 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
18c80 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
18c90 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
18ca0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
18cb0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
18cc0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
18cd0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18ce0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
18cf0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
18d00 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
18d10 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
18d20 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
18d30 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
18d40 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
18d50 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
18d60 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
18d70 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
18d80 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
18d90 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
18da0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
18db0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
18dc0 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
18dd0 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
18de0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
18df0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
18e00 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
18e10 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
18e20 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
18e30 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
18e40 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
18e50 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
18e60 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
18e70 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
18e80 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
18e90 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
18ea0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
18eb0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
18ec0 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
18ed0 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
18ee0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
18ef0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
18f00 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
18f10 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
18f20 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
18f30 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
18f40 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
18f50 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
18f60 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
18f70 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
18f80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
18f90 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
18fa0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
18fb0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
18fc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
18fd0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
18fe0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
18ff0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
19000 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
19010 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
19020 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
19030 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
19040 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
19050 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
19060 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19070 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
19080 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
19090 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
190a0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
190b0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
190c0 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
190d0 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
190e0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
190f0 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
19100 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  L sqlite3_last_i
19110 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
19120 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
19130 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
19140 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
19150 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
19160 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19170 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
19180 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
19190 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
191a0 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
191b0 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
191c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
191d0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
191e0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
191f0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
19200 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
19210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
19220 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
19230 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
19240 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
19250 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
19260 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
19270 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
19280 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
19290 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
192a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
192b0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
192c0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
192d0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
192e0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
192f0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
19300 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
19310 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
19320 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
19330 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
19340 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
19350 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
19360 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
19370 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
19380 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
19390 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
193a0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
193b0 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
193c0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
193d0 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
193e0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
193f0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
19400 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
19410 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
19420 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
19430 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
19440 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19450 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
19460 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
19470 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
19480 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
19490 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
194a0 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
194b0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
194c0 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
194d0 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
194e0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
194f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
19500 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
19510 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19520 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
19530 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
19540 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
19550 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
19560 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
19570 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
19580 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
19590 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
195a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
195b0 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
195c0 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
195d0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
195e0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
195f0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
19600 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
19610 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
19620 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
19630 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
19640 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
19650 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
19660 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
19670 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
19680 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
19690 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
196a0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
196b0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
196c0 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
196d0 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
196e0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
196f0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
19700 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19710 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
19720 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
19730 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
19740 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
19750 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
19760 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
19770 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
19780 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
19790 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
197a0 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
197b0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
197c0 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
197d0 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
197e0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
197f0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
19800 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
19810 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
19820 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
19830 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
19840 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
19850 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
19860 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
19870 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19880 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
19890 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
198a0 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
198b0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
198c0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
198d0 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
198e0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
198f0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
19900 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
19910 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
19920 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
19930 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
19940 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
19950 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19960 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
19970 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
19980 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
19990 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
199a0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
199b0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
199c0 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
199d0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
199e0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
199f0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
19a00 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
19a10 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
19a20 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
19a30 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
19a40 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
19a50 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
19a60 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
19a70 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
19a80 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
19a90 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
19aa0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
19ab0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
19ac0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
19ad0 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
19ae0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
19af0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
19b00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
19b10 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
19b20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19b30 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
19b40 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
19b50 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
19b60 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
19b70 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
19b80 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
19b90 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
19ba0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
19bb0 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
19bc0 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
19bd0 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
19be0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
19bf0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
19c00 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
19c10 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
19c20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19c30 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
19c40 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
19c50 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
19c60 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
19c70 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
19c80 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
19c90 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
19ca0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
19cb0 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
19cc0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
19cd0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
19ce0 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
19cf0 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
19d00 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
19d10 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
19d20 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
19d30 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
19d40 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
19d50 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
19d60 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
19d70 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
19d80 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
19d90 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
19da0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
19db0 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
19dc0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
19dd0 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
19de0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
19df0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
19e00 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
19e10 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
19e20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
19e30 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
19e40 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
19e50 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
19e60 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
19e70 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
19e80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19e90 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
19ea0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
19eb0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
19ec0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
19ed0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
19ee0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
19ef0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
19f00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
19f10 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
19f20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
19f30 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
19f40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19f50 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
19f60 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
19f70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
19f80 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
19f90 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
19fa0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
19fb0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
19fc0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
19fd0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
19fe0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
19ff0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1a000 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1a010 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1a020 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1a030 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1a040 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1a050 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1a060 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1a070 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1a080 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1a090 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1a0a0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1a0b0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1a0c0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1a0d0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1a0e0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1a0f0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1a100 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1a110 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1a120 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1a130 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1a140 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1a150 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1a160 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1a170 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1a180 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1a190 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1a1a0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1a1b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1a1c0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1a1d0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1a1e0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1a1f0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1a200 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1a210 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1a220 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1a230 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1a240 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1a250 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1a260 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1a270 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1a280 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1a290 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1a2a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1a2b0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1a2c0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1a2d0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1a2e0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1a2f0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1a300 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1a310 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1a320 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1a330 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1a340 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1a350 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1a360 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1a370 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1a380 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1a390 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1a3a0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1a3b0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1a3c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1a3d0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1a3e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1a3f0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1a400 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1a410 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1a420 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1a430 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a440 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1a450 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1a460 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1a470 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1a480 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1a490 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1a4a0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1a4b0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1a4c0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1a4d0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1a4e0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1a4f0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1a500 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1a510 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1a520 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1a530 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1a540 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1a550 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1a560 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1a570 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1a580 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1a590 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1a5a0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1a5b0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1a5c0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1a5d0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1a5e0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1a5f0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1a600 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1a610 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1a620 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
1a630 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a640 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
1a650 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1a660 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
1a670 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
1a680 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
1a690 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
1a6a0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
1a6b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1a6c0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
1a6d0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1a6e0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1a6f0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1a700 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
1a710 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
1a720 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
1a730 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
1a740 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
1a750 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
1a760 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
1a770 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
1a780 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
1a790 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1a7a0 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
1a7b0 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
1a7c0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
1a7d0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
1a7e0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
1a7f0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
1a800 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1a810 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
1a820 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
1a830 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
1a840 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1a850 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
1a860 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
1a870 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
1a880 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
1a890 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
1a8a0 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
1a8b0 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
1a8c0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
1a8d0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
1a8e0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
1a8f0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
1a900 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
1a910 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
1a920 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
1a930 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
1a940 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
1a950 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
1a960 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
1a970 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
1a980 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
1a990 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
1a9a0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
1a9b0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
1a9c0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
1a9d0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
1a9e0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
1a9f0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
1aa00 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
1aa10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1aa20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1aa30 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
1aa40 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
1aa50 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
1aa60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1aa70 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
1aa80 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
1aa90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
1aaa0 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
1aab0 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
1aac0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
1aad0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
1aae0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
1aaf0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
1ab00 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
1ab10 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
1ab20 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
1ab30 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
1ab40 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
1ab50 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
1ab60 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1ab70 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
1ab80 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
1ab90 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
1aba0 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
1abb0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1abc0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
1abd0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
1abe0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
1abf0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
1ac00 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1ac10 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
1ac20 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
1ac30 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1ac40 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
1ac50 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
1ac60 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
1ac70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1ac80 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
1ac90 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1aca0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
1acb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
1acc0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1acd0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
1ace0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1acf0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1ad00 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
1ad10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
1ad20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1ad30 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1ad40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1ad50 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1ad60 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
1ad70 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
1ad80 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  L sqlite3_comple
1ad90 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1ada0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1adb0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1adc0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1add0 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1ade0 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
1adf0 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
1ae00 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
1ae10 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
1ae20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1ae30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ae40 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1ae50 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
1ae60 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
1ae70 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
1ae80 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1ae90 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
1aea0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
1aeb0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1aec0 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
1aed0 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
1aee0 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1aef0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1af00 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
1af10 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1af20 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
1af30 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
1af40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1af50 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
1af60 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
1af70 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
1af80 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1af90 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
1afa0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1afb0 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
1afc0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1afd0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
1afe0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
1aff0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1b000 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
1b010 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
1b020 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
1b030 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1b040 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
1b050 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
1b060 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1b070 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
1b080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1b090 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1b0a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1b0b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1b0c0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
1b0d0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
1b0e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1b0f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1b100 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
1b110 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1b120 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1b130 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
1b140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1b150 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
1b160 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
1b170 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
1b180 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
1b190 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
1b1a0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1b1b0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1b1c0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1b1d0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1b1e0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1b1f0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1b200 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1b210 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1b220 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1b230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1b240 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1b250 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1b260 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1b270 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1b280 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1b290 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1b2a0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1b2b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1b2c0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1b2d0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1b2e0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1b2f0 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1b300 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1b310 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1b320 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1b330 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1b340 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1b350 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1b360 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1b370 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1b380 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1b390 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1b3a0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1b3b0 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1b3c0 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1b3d0 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1b3e0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1b3f0 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1b400 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1b410 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1b420 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1b430 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1b440 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1b450 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1b460 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1b470 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1b480 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1b490 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1b4a0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1b4b0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1b4c0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1b4d0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1b4e0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1b4f0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1b500 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1b510 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1b520 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1b530 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1b540 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1b550 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1b560 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1b570 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1b580 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1b590 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1b5a0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1b5b0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1b5c0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1b5d0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1b5e0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1b5f0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1b600 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1b610 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1b620 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1b630 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1b640 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1b650 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1b660 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1b670 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1b680 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1b690 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1b6a0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1b6b0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1b6c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1b6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b6e0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1b6f0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1b700 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1b710 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1b720 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1b730 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1b740 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1b750 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1b760 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1b770 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1b780 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1b790 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1b7a0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1b7b0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1b7c0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1b7d0 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1b7e0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1b7f0 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1b800 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1b810 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1b820 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1b830 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1b840 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1b850 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1b860 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1b870 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1b880 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1b890 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1b8a0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1b8b0 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1b8c0 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1b8d0 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1b8e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b8f0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1b900 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1b910 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1b920 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
1b930 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1b940 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1b950 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b960 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28  sqlite3*,int(*)(
1b970 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a  void*,int),void*
1b980 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b990 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
1b9a0 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44  imeout.** METHOD
1b9b0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1b9c0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
1b9d0 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
1b9e0 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
1b9f0 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
1ba00 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
1ba10 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
1ba20 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
1ba30 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
1ba40 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
1ba50 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
1ba60 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
1ba70 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
1ba80 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1ba90 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
1baa0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
1bab0 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
1bac0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1bad0 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
1bae0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
1baf0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
1bb00 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
1bb10 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
1bb20 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
1bb30 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1bb40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
1bb50 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
1bb60 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
1bb70 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
1bb80 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
1bb90 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
1bba0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1bbb0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1bbc0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
1bbd0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1bbe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bbf0 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20  n] at any given 
1bc00 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
1bc10 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1bc20 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
1bc30 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
1bc40 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
1bc50 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
1bc60 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
1bc70 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
1bc80 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
1bc90 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  leared.)^.**.** 
1bca0 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47  See also:  [PRAG
1bcb0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d  MA busy_timeout]
1bcc0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1bcd0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
1bce0 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  L sqlite3_busy_t
1bcf0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1bd00 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1bd10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1bd20 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1bd30 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1bd40 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1bd50 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1bd60 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1bd70 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1bd80 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1bd90 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1bda0 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1bdb0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1bdc0 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1bdd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1bde0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1bdf0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1be00 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1be10 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1be20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1be30 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1be40 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1be50 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1be60 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1be70 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1be80 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1be90 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1bea0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1beb0 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1bec0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1bed0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1bee0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1bef0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1bf00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1bf10 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1bf20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1bf30 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1bf40 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1bf50 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1bf60 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1bf70 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1bf80 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1bf90 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1bfa0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1bfb0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1bfc0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1bfd0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1bfe0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1bff0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1c000 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1c010 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1c020 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1c030 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1c040 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1c050 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1c060 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1c070 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1c080 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1c090 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1c0a0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1c0b0 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1c0c0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1c0d0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1c0e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c0f0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1c100 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1c110 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1c120 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1c130 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1c140 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1c150 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1c160 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1c170 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1c180 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1c190 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1c1a0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1c1b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1c1c0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1c1d0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1c1e0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1c1f0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1c200 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1c210 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1c220 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1c230 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1c240 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1c250 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1c260 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c270 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1c280 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1c290 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1c2a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1c2b0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1c2c0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1c2d0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1c2e0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1c2f0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1c300 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1c310 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c320 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1c330 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1c340 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1c350 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1c360 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1c370 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1c380 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1c390 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1c3a0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1c3b0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1c3c0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1c3d0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1c3e0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1c3f0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c400 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c410 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1c420 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1c430 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1c440 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1c450 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1c460 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1c470 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1c480 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1c490 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c4a0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1c4b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1c4c0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1c4d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c4e0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1c4f0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1c500 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1c510 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1c520 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1c530 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c540 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1c550 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1c560 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1c570 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1c580 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1c590 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1c5a0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1c5b0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1c5c0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1c5d0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1c5e0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1c5f0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1c600 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1c610 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1c620 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1c630 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1c640 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1c650 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1c660 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1c670 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1c680 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1c690 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1c6a0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1c6b0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1c6c0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1c6d0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1c6e0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1c6f0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1c700 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c710 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1c720 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c730 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1c740 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1c750 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1c760 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1c770 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1c780 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1c790 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1c7a0 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1c7b0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1c7c0 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1c7d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1c7e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1c7f0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1c800 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1c810 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1c820 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1c830 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1c840 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1c850 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1c860 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1c870 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1c880 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1c890 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1c8a0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1c8b0 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1c8c0 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1c8d0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1c8e0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1c8f0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1c900 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1c910 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1c920 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1c930 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1c940 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1c950 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1c960 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1c970 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1c980 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1c990 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
1c9a0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1c9b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c9c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1c9d0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1c9e0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1c9f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1ca00 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1ca10 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1ca20 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1ca30 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1ca40 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1ca50 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1ca60 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1ca70 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1ca80 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1ca90 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1caa0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1cab0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1cac0 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1cad0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1cae0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1caf0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1cb00 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1cb10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1cb20 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
1cb30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1cb40 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1cb50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1cb60 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1cb70 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1cb80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1cb90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1cba0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1cbb0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1cbc0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1cbd0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1cbe0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1cbf0 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1cc00 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1cc10 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1cc20 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69  mon K&R formatti
1cc30 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70  ng options,.** p
1cc40 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1cc50 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1cc60 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c   formats, detail
1cc70 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74  ed below..** Not
1cc80 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74  e that some of t
1cc90 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20  he more obscure 
1cca0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1ccb0 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a  ns from recent.*
1ccc0 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e  * C-library stan
1ccd0 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65  dards are omitte
1cce0 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c  d from this impl
1ccf0 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ementation..**.*
1cd00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1cd10 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1cd20 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1cd30 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1cd40 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1cd50 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1cd60 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1cd70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1cd80 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1cd90 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1cda0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1cdb0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1cdc0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1cdd0 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1cde0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1cdf0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1ce00 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1ce10 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1ce20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1ce30 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1ce40 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1ce50 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1ce60 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1ce70 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1ce80 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1ce90 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1cea0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1ceb0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1cec0 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1ced0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1cee0 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1cef0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1cf00 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1cf10 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1cf20 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1cf30 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1cf40 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1cf50 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1cf60 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1cf70 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1cf80 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1cf90 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1cfa0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1cfb0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1cfc0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1cfd0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1cfe0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1cff0 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1d000 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d010 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1d020 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1d030 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1d040 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1d050 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1d060 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1d070 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1d080 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1d090 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1d0a0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1d0b0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1d0c0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1d0d0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1d0e0 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1d0f0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1d100 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1d110 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1d120 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1d130 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1d140 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1d150 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1d160 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1d170 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1d180 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1d190 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1d1a0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1d1b0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1d1c0 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1d1d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1d1e0 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1d1f0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1d200 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1d210 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1d220 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1d230 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1d240 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1d250 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1d260 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1d270 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1d280 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d290 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1d2a0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1d2b0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1d2c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1d2d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1d2e0 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1d2f0 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1d300 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1d310 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1d320 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1d330 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1d340 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1d350 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1d360 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1d370 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1d380 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1d390 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1d3a0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77   "%q", "%Q", "%w
1d3b0 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  " and "%z" optio
1d3c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1d3d0 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1d3e0 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1d3f0 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1d400 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1d410 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1d420 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1d430 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1d440 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1d450 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1d460 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1d470 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1d480 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1d490 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1d4a0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1d4b0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1d4c0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1d4d0 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1d4e0 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1d4f0 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1d500 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1d510 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1d520 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1d530 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1d540 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1d550 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d560 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1d570 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1d580 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1d590 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1d5a0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1d5b0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1d5c0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1d5d0 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1d5e0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d5f0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1d600 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1d610 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1d620 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1d630 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1d640 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1d650 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1d660 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1d670 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1d680 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d690 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1d6a0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1d6b0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1d6c0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1d6d0 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1d6e0 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1d6f0 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
1d700 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
1d710 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1d720 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1d730 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1d740 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
1d750 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
1d760 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1d770 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1d780 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
1d790 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
1d7a0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
1d7b0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
1d7c0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
1d7d0 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
1d7e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1d7f0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1d800 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1d810 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
1d820 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
1d830 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1d840 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
1d850 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
1d860 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
1d870 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
1d880 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
1d890 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
1d8a0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
1d8b0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
1d8c0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
1d8d0 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
1d8e0 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
1d8f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
1d900 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
1d910 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
1d920 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
1d930 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
1d940 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
1d950 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
1d960 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
1d970 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
1d980 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
1d990 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
1d9a0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
1d9b0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
1d9c0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
1d9d0 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
1d9e0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
1d9f0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
1da00 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1da10 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1da20 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1da30 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1da40 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
1da50 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1da60 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1da70 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1da80 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1da90 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1daa0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1dab0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
1dac0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
1dad0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
1dae0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
1daf0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
1db00 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
1db10 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
1db20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1db30 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74  (The "%w" format
1db40 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c  ting option is l
1db50 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20  ike "%q" except 
1db60 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
1db70 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e  to.** be contain
1db80 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65  ed within double
1db90 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20  -quotes instead 
1dba0 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  of single quotes
1dbb0 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61  , and it.** esca
1dbc0 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71  pes the double-q
1dbd0 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69  uote character i
1dbe0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69  nstead of the si
1dbf0 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68  ngle-quote.** ch
1dc00 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20  aracter.)^  The 
1dc10 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1dc20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64  option is intend
1dc30 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e  ed for safely in
1dc40 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65  serting.** table
1dc50 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   and column name
1dc60 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75  s into a constru
1dc70 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  cted SQL stateme
1dc80 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  nt..**.** ^(The 
1dc90 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1dca0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1dcb0 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1dcc0 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1dcd0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1dce0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1dcf0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1dd00 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1dd10 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1dd20 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1dd30 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1dd40 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  g.)^.*/.SQLITE_A
1dd50 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  PI char *SQLITE_
1dd60 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 6d 70  CDECL sqlite3_mp
1dd70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1dd80 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41  *,...);.SQLITE_A
1dd90 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  PI char *SQLITE_
1dda0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1ddb0 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1ddc0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1ddd0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1dde0 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71  *SQLITE_CDECL sq
1ddf0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1de00 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1de10 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49  har*, ...);.SQLI
1de20 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c  TE_API char *SQL
1de30 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1de40 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1de50 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1de60 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1de70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1de80 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1de90 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1dea0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1deb0 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1dec0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1ded0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1dee0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1def0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1df00 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1df10 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1df20 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1df30 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1df40 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1df50 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1df60 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1df70 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1df80 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1df90 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1dfa0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1dfb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1dfc0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1dfd0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1dfe0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1dff0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1e000 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1e010 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1e020 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1e030 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1e040 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1e050 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1e060 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1e070 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1e080 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1e090 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1e0a0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1e0b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e0c0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1e0d0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1e0e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1e0f0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1e100 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1e110 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1e120 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1e130 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1e140 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1e150 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1e160 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1e170 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1e180 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1e190 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1e1a0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1e1b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1e1c0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1e1d0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1e1e0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1e1f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1e200 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e210 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1e220 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1e230 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1e240 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1e250 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1e260 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1e270 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1e280 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1e290 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1e2a0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1e2b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1e2c0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1e2d0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1e2e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1e2f0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1e300 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1e310 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1e320 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1e330 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1e340 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1e350 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1e360 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1e370 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1e380 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1e390 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1e3a0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1e3b0 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1e3c0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1e3d0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1e3e0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1e3f0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1e400 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1e410 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1e420 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1e430 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1e440 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e450 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1e460 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1e470 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1e480 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1e490 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1e4a0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1e4b0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1e4c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1e4d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1e4e0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1e4f0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1e500 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1e510 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1e520 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1e530 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1e540 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1e550 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e560 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1e570 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1e580 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1e590 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1e5a0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1e5b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1e5c0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1e5d0 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1e5e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1e5f0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1e600 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1e610 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1e620 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1e630 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1e640 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1e650 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1e660 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1e670 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1e680 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1e690 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1e6a0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1e6b0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1e6c0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1e6d0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1e6e0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1e6f0 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1e700 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1e710 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1e720 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1e730 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1e740 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1e750 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1e760 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1e770 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1e780 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1e790 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1e7a0 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1e7b0 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1e7c0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1e7d0 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1e7e0 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1e7f0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1e800 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1e810 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1e820 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1e830 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1e840 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1e850 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1e860 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1e870 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1e880 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1e890 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1e8a0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1e8b0 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1e8c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1e8d0 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
1e8e0 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
1e8f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e900 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
1e910 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1e920 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
1e930 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
1e940 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
1e950 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1e960 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
1e970 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
1e980 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
1e990 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
1e9a0 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1e9b0 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
1e9c0 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
1e9d0 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
1e9e0 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
1e9f0 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
1ea00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
1ea10 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
1ea20 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
1ea30 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
1ea40 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
1ea50 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
1ea60 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1ea70 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
1ea80 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
1ea90 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
1eaa0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1eab0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1eac0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1ead0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
1eae0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
1eaf0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1eb00 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
1eb10 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
1eb20 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1eb30 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1eb40 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1eb50 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1eb60 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1eb70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1eb80 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1eb90 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1eba0 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1ebb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1ebc0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1ebd0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1ebe0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1ebf0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1ec00 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1ec10 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1ec20 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1ec30 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1ec40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1ec50 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1ec60 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1ec70 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1ec80 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1ec90 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1eca0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1ecb0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1ecc0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1ecd0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1ece0 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1ecf0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1ed00 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1ed10 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1ed20 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1ed30 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1ed40 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1ed50 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1ed60 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1ed70 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1ed80 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1ed90 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1eda0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1edb0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1edc0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1edd0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1ede0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1edf0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1ee00 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1ee10 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1ee20 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1ee30 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1ee40 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1ee50 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1ee60 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1ee70 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1ee80 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1ee90 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1eea0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1eeb0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1eec0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1eed0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1eee0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1eef0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1ef00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1ef10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1ef20 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1ef30 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1ef40 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1ef50 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1ef60 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1ef70 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1ef80 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1ef90 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1efa0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1efb0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1efc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1efd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1efe0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
1eff0 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
1f000 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1f010 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1f020 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1f030 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
1f040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1f050 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  (sqlite3_uint64)
1f060 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1f070 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
1f080 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  L sqlite3_reallo
1f090 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  c(void*, int);.S
1f0a0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1f0b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1f0c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f0d0 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
1f0e0 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  uint64);.SQLITE_
1f0f0 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
1f100 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1f110 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c  free(void*);.SQL
1f120 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1f130 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  uint64 SQLITE_ST
1f140 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 73  DCALL sqlite3_ms
1f150 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
1f160 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1f170 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1f180 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1f190 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1f1a0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1f1b0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1f1c0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1f1d0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1f1e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1f1f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1f200 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1f210 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1f220 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1f230 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1f240 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1f250 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1f260 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1f270 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1f280 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1f290 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1f2a0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1f2b0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1f2c0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1f2d0 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1f2e0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1f2f0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1f300 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1f310 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1f320 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1f330 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f340 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1f350 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1f360 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1f370 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1f380 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1f390 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1f3a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1f3b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1f3c0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1f3d0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1f3e0 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1f3f0 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1f400 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1f410 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1f420 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1f430 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1f440 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1f450 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1f460 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1f470 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1f480 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1f490 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1f4a0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1f4b0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1f4c0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1f4d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1f4e0 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1f4f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1f500 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1f510 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1f520 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1f530 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1f540 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1f550 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f560 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1f570 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1f580 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1f590 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
1f5a0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1f5b0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1f5c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1f5d0 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  sed(void);.SQLIT
1f5e0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1f5f0 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
1f600 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  LL sqlite3_memor
1f610 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
1f620 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
1f630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
1f640 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
1f650 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
1f660 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
1f670 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
1f680 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
1f690 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
1f6a0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
1f6b0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
1f6c0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
1f6d0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1f6e0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
1f6f0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
1f700 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
1f710 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
1f720 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
1f730 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
1f740 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
1f750 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
1f760 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
1f770 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
1f780 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1f790 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
1f7a0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
1f7b0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
1f7c0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
1f7d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
1f7e0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1f7f0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
1f800 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
1f810 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
1f820 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
1f830 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
1f840 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
1f850 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
1f860 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
1f870 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
1f880 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
1f890 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
1f8a0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
1f8b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
1f8c0 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
1f8d0 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
1f8e0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1f8f0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1f900 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
1f910 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
1f920 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1f930 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1f940 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
1f950 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
1f960 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
1f970 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
1f980 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
1f990 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
1f9a0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1f9b0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1f9c0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1f9d0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1f9e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1f9f0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1fa00 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49   method..*/.SQLI
1fa10 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
1fa20 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1fa30 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1fa40 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1fa50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fa60 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1fa70 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1fa80 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
1fa90 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1faa0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1fab0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1fac0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1fad0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1fae0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1faf0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1fb00 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1fb10 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1fb20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fb30 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1fb40 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1fb50 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1fb60 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1fb70 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1fb80 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1fb90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fba0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1fbb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1fbc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1fbd0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1fbe0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1fbf0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1fc00 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1fc10 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1fc20 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1fc30 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1fc40 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1fc50 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fc60 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1fc70 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1fc80 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1fc90 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1fca0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fcb0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1fcc0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1fcd0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1fce0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1fcf0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1fd00 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1fd10 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1fd20 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1fd30 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1fd40 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1fd50 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1fd60 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1fd70 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1fd80 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1fd90 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1fda0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1fdb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fdc0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1fdd0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1fde0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1fdf0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1fe00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1fe10 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1fe20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fe30 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1fe40 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1fe50 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1fe60 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1fe70 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1fe80 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1fe90 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1fea0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1feb0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1fec0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1fed0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1fee0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1fef0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1ff00 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1ff10 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1ff20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1ff30 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1ff40 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1ff50 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1ff60 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1ff70 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1ff80 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1ff90 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1ffa0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1ffb0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1ffc0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1ffd0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ffe0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1fff0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
20000 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
20010 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
20020 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
20030 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
20040 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
20050 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
20060 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
20070 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
20080 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
20090 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
200a0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
200b0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
200c0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
200d0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
200e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
200f0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
20100 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
20110 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
20120 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
20130 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
20140 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20150 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
20160 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
20170 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
20180 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
20190 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
201a0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
201b0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
201c0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
201d0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
201e0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
201f0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
20200 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
20210 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
20220 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
20230 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
20240 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
20250 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
20260 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
20270 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
20280 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
20290 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
202a0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
202b0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
202c0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
202d0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
202e0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
202f0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
20300 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20310 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
20320 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
20330 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
20340 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
20350 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
20360 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
20370 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
20380 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
20390 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
203a0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
203b0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
203c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
203d0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
203e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
203f0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
20400 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
20410 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
20420 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20430 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
20440 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
20450 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
20460 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
20470 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
20480 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
20490 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
204a0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
204b0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
204c0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
204d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
204e0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
204f0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
20500 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
20510 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
20520 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
20530 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
20540 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
20550 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
20560 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
20570 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
20580 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
20590 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
205a0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
205b0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
205c0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
205d0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
205e0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
205f0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
20600 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
20610 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
20620 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
20630 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
20640 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
20650 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
20660 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
20670 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
20680 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
20690 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
206a0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
206b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
206c0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
206d0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
206e0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
206f0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20700 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
20710 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
20720 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
20730 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
20740 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
20750 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
20760 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
20770 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
20780 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
20790 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
207a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
207b0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
207c0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
207d0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
207e0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
207f0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
20800 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
20810 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
20820 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
20830 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
20840 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
20850 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
20860 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
20870 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
20880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20890 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
208a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
208b0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
208c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
208d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
208e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
208f0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
20900 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
20910 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
20920 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
20930 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
20940 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
20950 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
20960 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
20970 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
20980 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
20990 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
209a0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
209b0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
209c0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
209d0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
209e0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
209f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
20a00 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
20a10 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
20a20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20a30 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
20a40 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
20a50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
20a60 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
20a70 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
20a80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20a90 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
20aa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20ab0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
20ac0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
20ad0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
20ae0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
20af0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
20b00 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
20b10 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
20b20 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
20b30 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
20b40 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
20b50 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
20b60 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
20b70 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
20b80 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
20b90 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
20ba0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51  ma change..*/.SQ
20bb0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
20bc0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
20bd0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20be0 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
20bf0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
20c00 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
20c10 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
20c20 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
20c30 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
20c40 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
20c50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20c60 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
20c70 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
20c80 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
20c90 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
20ca0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20cb0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
20cc0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
20cd0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
20ce0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
20cf0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
20d00 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
20d10 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
20d20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
20d30 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
20d40 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
20d50 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
20d60 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
20d70 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
20d80 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
20d90 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
20da0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
20db0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
20dc0 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
20dd0 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
20de0 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74  ion mode].** ret
20df0 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b  urned from the [
20e00 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
20e10 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
20e20 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
20e30 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
20e40 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
20e50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
20e60 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
20e70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
20e80 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
20e90 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
20ea0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
20eb0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
20ec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20ed0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
20ee0 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
20ef0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
20f00 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
20f10 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
20f20 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
20f30 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
20f40 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
20f50 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
20f60 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
20f70 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
20f80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
20f90 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
20fa0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
20fb0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
20fc0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
20fd0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
20fe0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
20ff0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
21000 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
21010 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21020 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
21030 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
21040 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
21050 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
21060 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
21070 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
21080 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
21090 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
210a0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
210b0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
210c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
210d0 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
210e0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
210f0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
21100 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
21110 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
21120 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
21130 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
21140 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
21150 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
21160 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
21170 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
21180 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
21190 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
211a0 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
211b0 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
211c0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
211d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
211e0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
211f0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
21200 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
21210 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
21220 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
21230 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
21240 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
21250 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
21260 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
21270 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
21280 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
21290 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
212a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
212b0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
212c0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
212d0 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
212e0 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
212f0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
21300 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
21310 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21330 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
21340 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
21350 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21360 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21380 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
21390 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
213a0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
213b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
213c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
213d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
213e0 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
213f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21400 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21420 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
21430 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
21440 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
21450 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21470 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
21480 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
21490 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
214a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
214b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
214c0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
214d0 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
214e0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
214f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21500 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21510 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
21520 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
21530 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
21540 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21550 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
21560 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
21570 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
21580 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21590 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
215a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
215b0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
215c0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
215d0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
215e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
215f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21600 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
21610 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
21620 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21630 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21640 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21650 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
21660 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21670 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21680 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21690 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
216a0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
216b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
216c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
216d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
216e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
216f0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
21700 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
21710 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21720 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21730 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
21740 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
21750 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
21760 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21770 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21780 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
21790 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
217a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
217b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
217c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
217d0 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
217e0 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
217f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21800 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21810 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21820 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
21830 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
21840 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21850 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21860 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21870 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
21880 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
21890 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
218a0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
218b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
218c0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
218d0 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
218e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
218f0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
21900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21910 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
21920 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
21930 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
21940 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21950 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
21960 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
21970 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
21980 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
21990 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
219a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
219b0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
219c0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
219d0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
219e0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
219f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
21a00 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
21a10 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
21a20 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
21a30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
21a50 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
21a60 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
21a70 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
21a80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21a90 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
21aa0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
21ab0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
21ac0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
21ad0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21ae0 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
21af0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
21b00 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
21b10 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21b20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21b30 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
21b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
21b50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21b60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21b70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21b80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
21b90 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
21ba0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21bb0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
21bc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21bd0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
21be0 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
21bf0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21c00 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
21c10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21c20 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
21c30 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
21c40 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
21c50 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
21c60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21c70 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
21c80 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
21c90 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
21ca0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
21cb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21cc0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
21cd0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
21ce0 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
21cf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21d00 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  E_RECURSIVE     
21d10 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e         33   /* N
21d20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
21d30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21d40 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
21d50 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
21d60 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
21d70 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
21d80 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73  lite3.**.** Thes
21d90 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
21da0 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20 74  eprecated. Use t
21db0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
21dc0 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  e_v2()] interfac
21dd0 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20  e.** instead of 
21de0 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73  the routines des
21df0 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  cribed here..**.
21e00 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
21e10 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
21e20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
21e30 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
21e40 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
21e50 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
21e60 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
21e70 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
21e80 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
21e90 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
21ea0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
21eb0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
21ec0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
21ed0 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
21ee0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
21ef0 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
21f00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
21f10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
21f20 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
21f30 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
21f40 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
21f50 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
21f60 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
21f70 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
21f80 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
21f90 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
21fa0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
21fb0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
21fc0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
21fd0 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
21fe0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
21ff0 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
22000 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
22010 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
22020 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
22030 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
22040 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
22050 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
22060 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
22070 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
22080 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
22090 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
220a0 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
220b0 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
220c0 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
220d0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
220e0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
220f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
22100 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
22110 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
22120 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
22130 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
22140 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
22150 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
22160 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
22170 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
22180 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
22190 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
221a0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
221b0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
221c0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
221d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
221e0 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
221f0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
22200 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
22210 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
22220 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
22230 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
22240 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
22250 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
22260 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
22270 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
22280 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
22290 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
222a0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
222b0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
222c0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
222d0 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
222e0 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
222f0 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
22300 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
22310 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
22320 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
22330 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
22340 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
22350 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
22360 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
22370 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
22380 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
22390 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
223a0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 53 51  RECATED void *SQ
223b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
223c0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
223d0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54  e3*,.   void(*xT
223e0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
223f0 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
22400 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
22410 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
22420 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
22430 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  ALL sqlite3_prof
22440 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
22450 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
22460 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
22470 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
22480 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
22490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
224a0 20 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64   Trace Event Cod
224b0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
224c0 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a  SQLITE_TRACE.**.
224d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
224e0 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73  ts identify clas
224f0 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68  ses of events th
22500 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f  at can be monito
22510 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  red.** using the
22520 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
22530 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f  v2()] tracing lo
22540 67 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20  gic.  The third 
22550 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
22560 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
22570 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20  ()] is an OR-ed 
22580 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f  combination of o
22590 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a  ne or more of.**
225a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
225b0 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20  onstants.  ^The 
225c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
225d0 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
225e0 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f  back.** is one o
225f0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
22600 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
22610 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e   New tracing con
22620 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64  stants may be ad
22630 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
22640 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  leases..**.** ^A
22650 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
22660 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  has four argumen
22670 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c  ts: xCallback(T,
22680 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
22690 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
226a0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  e of the integer
226b0 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76   type codes abov
226c0 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  e..** ^The C arg
226d0 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
226e0 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
226f0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
22700 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
22710 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
22720 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
22730 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  )]..** The P and
22740 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
22750 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
22760 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
22770 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  on T..**.** <dl>
22780 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
22790 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51  CE_STMT]] <dt>SQ
227a0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c  LITE_TRACE_STMT<
227b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
227c0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
227d0 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  T callback is in
227e0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65  voked when a pre
227f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
22800 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  ** first begins 
22810 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73  running and poss
22820 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69  ibly at other ti
22830 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a  mes during the.*
22840 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  * execution of t
22850 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
22860 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61  ement, such as a
22870 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65  t the start of e
22880 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73  ach.** trigger s
22890 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20  ubprogram. ^The 
228a0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
228b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
228c0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
228d0 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61  ement]. ^The X a
228e0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
228f0 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
22900 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
22910 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20   unexpanded SQL 
22920 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70  text of the prep
22930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
22940 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
22950 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
22960 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69  tes the invocati
22970 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e  on of a trigger.
22980 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20    ^The callback 
22990 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74  can compute.** t
229a0 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61  he same text tha
229b0 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65  t would have bee
229c0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
229d0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
229e0 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e  3_trace()].** in
229f0 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67  terface by using
22a00 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
22a10 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69  when X begins wi
22a20 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f  th "--" and invo
22a30 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  king.** [sqlite3
22a40 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
22a50 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  ] otherwise..**.
22a60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
22a70 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e  E_PROFILE]] <dt>
22a80 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
22a90 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FILE</dt>.** <dd
22aa0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
22ab0 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61  E_PROFILE callba
22ac0 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72  ck provides appr
22ad0 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61  oximately the sa
22ae0 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  me.** informatio
22af0 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64  n as is provided
22b00 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
22b10 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c  _profile()] call
22b20 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  back..** ^The P 
22b30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
22b40 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
22b50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b60 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
22b70 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
22b80 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  o a 64-bit integ
22b90 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20  er which is the 
22ba0 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20  estimated of.** 
22bb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
22bc0 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68  nosecond that th
22bd0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
22be0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
22bf0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
22c00 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
22c10 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
22c20 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74  ed when the stat
22c30 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a  ement finishes..
22c40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
22c50 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53  RACE_ROW]] <dt>S
22c60 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c  QLITE_TRACE_ROW<
22c70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
22c80 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
22c90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22ca0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
22cb0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
22cc0 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20  ement generates 
22cd0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
22ce0 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68  result.  .** ^Th
22cf0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
22d00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
22d10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22d20 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
22d30 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
22d40 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  nused..**.** [[S
22d50 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
22d60 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
22d70 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a  RACE_CLOSE</dt>.
22d80 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
22d90 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61  E_TRACE_CLOSE ca
22da0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22db0 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  d when a databas
22dc0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
22dd0 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20  closes..** ^The 
22de0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
22df0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
22e00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22e10 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  ion] object.** a
22e20 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  nd the X argumen
22e30 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20  t is unused..** 
22e40 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
22e50 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
22e60 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64  MT       0x01.#d
22e70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
22e80 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78  CE_PROFILE    0x
22e90 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
22ea0 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20  E_TRACE_ROW     
22eb0 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20     0x04.#define 
22ec0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
22ed0 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a  SE      0x08../*
22ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
22ef0 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20  L Trace Hook.** 
22f00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
22f10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22f20 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c  e3_trace_v2(D,M,
22f30 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  X,P) interface r
22f40 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65  egisters a trace
22f50 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
22f60 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20  ction X against 
22f70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22f80 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70  tion] D, using p
22f90 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a  roperty mask M.*
22fa0 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f  * and context po
22fb0 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68  inter P.  ^If th
22fc0 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a  e X callback is.
22fd0 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68  ** NULL or if th
22fe0 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f  e M mask is zero
22ff0 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69  , then tracing i
23000 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  s disabled.  The
23010 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73  .** M argument s
23020 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74  hould be the bit
23030 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69  wise OR-ed combi
23040 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72  nation of.** zer
23050 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54  o or more [SQLIT
23060 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e  E_TRACE] constan
23070 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  ts..**.** ^Each 
23080 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73  call to either s
23090 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
230a0 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
230b0 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a  v2() overrides .
230c0 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79  ** (cancels) any
230d0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
230e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
230f0 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
23100 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  _v2()..**.** ^Th
23110 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e X callback is 
23120 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
23130 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e   any of the even
23140 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ts identified by
23150 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75   .** mask M occu
23160 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72  r.  ^The integer
23170 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
23180 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  om the callback 
23190 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  is currently.** 
231a0 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20  ignored, though 
231b0 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20  this may change 
231c0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
231d0 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a  es.  Callback.**
231e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
231f0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a   should return z
23200 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75  ero to ensure fu
23210 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69  ture compatibili
23220 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  ty..**.** ^A tra
23230 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ce callback is i
23240 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72  nvoked with four
23250 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c   arguments: call
23260 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
23270 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
23280 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
23290 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a  [SQLITE_TRACE].*
232a0 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69  * constants to i
232b0 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20  ndicate why the 
232c0 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76  callback was inv
232d0 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  oked..** ^The C 
232e0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
232f0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
23300 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  t pointer..** Th
23310 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
23320 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
23330 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
23340 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
23350 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
23360 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66  race_v2() interf
23370 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
23380 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c  to replace the l
23390 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
233a0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  ces [sqlite3_tra
233b0 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ce()] and [sqlit
233c0 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62  e3_profile()], b
233d0 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20  oth of which.** 
233e0 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a  are deprecated..
233f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
23400 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
23410 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
23420 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  2(.  sqlite3*,. 
23430 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c   unsigned uMask,
23440 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63  .  int(*xCallbac
23450 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64  k)(unsigned,void
23460 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a  *,void*,void*),.
23470 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a    void *pCtx.);.
23480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23490 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
234a0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
234b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
234c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
234d0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
234e0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
234f0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
23500 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
23510 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
23520 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
23530 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
23540 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
23550 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
23560 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
23570 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23580 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
23590 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
235a0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
235b0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
235c0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
235d0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
235e0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
235f0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
23600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
23610 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
23620 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
23630 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
23640 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
23650 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
23660 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
23670 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
23680 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
23690 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
236a0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
236b0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
236c0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
236d0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
236e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
236f0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
23700 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
23710 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
23720 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
23730 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
23740 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
23750 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23760 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
23770 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
23780 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
23790 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
237a0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
237b0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
237c0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
237d0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
237e0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
237f0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
23800 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
23810 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
23820 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
23830 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
23840 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
23850 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
23860 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
23870 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
23880 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
23890 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
238a0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
238b0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
238c0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
238d0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
238e0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
238f0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
23900 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
23910 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
23920 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
23930 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
23940 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
23950 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
23960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23970 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
23980 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
23990 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
239a0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
239b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
239c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
239d0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
239e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
239f0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
23a00 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
23a10 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
23a20 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51  agraph..**.*/.SQ
23a30 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
23a40 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
23a50 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
23a60 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
23a70 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
23a80 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
23a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
23aa0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
23ab0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
23ac0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73  * CONSTRUCTOR: s
23ad0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
23ae0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
23af0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
23b00 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
23b10 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
23b20 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
23b30 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
23b40 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
23b50 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
23b60 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
23b70 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
23b80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23b90 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
23ba0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
23bb0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
23bc0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
23bd0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
23be0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
23bf0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
23c00 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
23c10 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
23c20 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
23c30 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
23c40 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
23c50 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
23c60 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
23c70 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
23c80 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
23c90 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
23ca0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
23cb0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
23cc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
23cd0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
23ce0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
23cf0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
23d00 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
23d10 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
23d20 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
23d30 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
23d40 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
23d50 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
23d60 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
23d70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
23d80 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
23d90 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
23da0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
23db0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
23dc0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
23dd0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
23de0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
23df0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
23e00 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
23e10 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
23e20 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
23e30 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
23e40 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65  encoding will be
23e50 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62   UTF-8 for datab
23e60 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69  ases created usi
23e70 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  ng.** sqlite3_op
23e80 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
23e90 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65  open_v2().  ^The
23ea0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
23eb0 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a  g for databases.
23ec0 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  ** created using
23ed0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23ee0 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ) will be UTF-16
23ef0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23f00 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
23f10 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
23f20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
23f30 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
23f40 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
23f50 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
23f60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
23f70 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
23f80 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
23f90 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
23fa0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
23fb0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
23fc0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
23fd0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
23fe0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
23ff0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
24000 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
24010 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
24020 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
24030 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
24040 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
24050 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
24060 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
24070 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
24080 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
24090 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
240a0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
240b0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
240c0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
240d0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
240e0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
240f0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
24100 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
24110 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
24120 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
24130 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
24140 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
24150 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
24160 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
24170 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
24180 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
24190 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
241a0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
241b0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
241c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
241d0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
241e0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
241f0 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
24200 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
24210 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
24220 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
24230 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
24240 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
24250 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
24260 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
24270 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24280 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
24290 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
242a0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
242b0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
242c0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
242d0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
242e0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
242f0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
24300 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
24310 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
24320 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
24330 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
24340 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
24350 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
24360 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
24370 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
24380 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
24390 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
243a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
243b0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
243c0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
243d0 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
243e0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
243f0 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
24400 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
24410 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
24420 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
24430 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
24440 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
24450 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
24460 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
24470 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
24480 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
24490 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
244a0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
244b0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
244c0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
244d0 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
244e0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
244f0 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
24500 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
24510 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
24520 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
24530 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
24540 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
24550 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
24560 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24570 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
24580 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
24590 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
245a0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
245b0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
245c0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
245d0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
245e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
245f0 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
24600 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
24610 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
24620 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
24630 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24640 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
24650 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
24660 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
24670 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
24680 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
24690 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
246a0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
246b0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
246c0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
246d0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
246e0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
246f0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24700 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
24710 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
24720 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
24730 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
24740 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
24750 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
24760 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
24770 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
24780 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
24790 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
247a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
247b0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
247c0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
247d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
247e0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
247f0 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
24800 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
24810 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
24820 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
24830 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
24840 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
24850 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
24860 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
24870 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
24880 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
24890 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
248a0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
248b0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
248c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
248d0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
248e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
248f0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
24900 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
24910 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
24920 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
24930 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
24940 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
24950 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
24960 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
24970 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
24980 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
24990 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
249a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
249b0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
249c0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
249d0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
249e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
249f0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
24a00 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
24a10 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
24a20 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
24a30 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
24a40 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
24a50 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
24a60 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
24a70 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
24a80 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
24a90 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
24aa0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
24ab0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
24ac0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
24ad0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
24ae0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
24af0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
24b00 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
24b10 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
24b20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
24b30 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
24b40 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
24b50 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
24b60 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
24b70 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
24b80 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
24b90 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
24ba0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
24bb0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
24bc0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
24bd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24be0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24bf0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
24c00 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
24c10 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
24c20 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
24c30 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
24c40 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
24c50 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
24c60 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
24c70 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
24c80 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
24c90 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
24ca0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
24cb0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
24cc0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
24cd0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
24ce0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
24cf0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
24d00 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
24d10 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
24d20 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
24d30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24d40 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
24d50 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
24d60 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
24d70 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
24d80 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
24d90 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
24da0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
24db0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
24dc0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
24dd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
24de0 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
24df0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
24e00 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
24e10 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
24e20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
24e30 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
24e40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
24e50 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
24e60 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
24e70 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
24e80 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
24e90 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
24ea0 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
24eb0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
24ec0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
24ed0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
24ee0 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
24ef0 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
24f00 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
24f10 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
24f20 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
24f30 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
24f40 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
24f50 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
24f60 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
24f70 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
24f80 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
24f90 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
24fa0 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
24fb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
24fc0 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
24fd0 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
24fe0 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
24ff0 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
25000 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
25010 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
25020 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
25030 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
25040 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
25050 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
25060 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
25070 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
25080 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
25090 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
250a0 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
250b0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
250c0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
250d0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
250e0 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
250f0 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
25100 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
25110 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
25120 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
25130 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
25140 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
25150 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
25160 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
25170 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  * ^(On windows, 
25180 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
25190 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
251a0 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
251b0 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
251c0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
251d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  .)^.**.** [[core
251e0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
251f0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
25200 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
25210 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
25220 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
25230 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
25240 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
25250 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
25260 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
25270 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
25280 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
25290 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69  Lite and its bui
252a0 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e  lt-in [VFSes] in
252b0 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66  terpret the.** f
252c0 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70  ollowing query p
252d0 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
252e0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
252f0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
25300 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
25310 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
25320 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
25330 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
25340 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
25350 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
25360 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
25370 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
25380 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
25390 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
253a0 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
253b0 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
253c0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
253d0 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
253e0 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
253f0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
25400 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
25410 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
25420 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
25430 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
25440 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
25450 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
25460 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
25470 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
25480 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
25490 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
254a0 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
254b0 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
254c0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
254d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
254e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
254f0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
25500 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
25510 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
25520 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
25530 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
25540 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
25550 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
25560 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
25570 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
25580 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
25590 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
255a0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
255b0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
255c0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
255d0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
255e0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
255f0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
25600 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
25610 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
25620 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
25630 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
25640 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
25650 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
25660 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
25670 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
25680 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
25690 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
256a0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
256b0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
256c0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
256d0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
256e0 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
256f0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
25700 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
25710 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
25720 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
25730 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
25740 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
25750 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
25760 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
25770 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
25780 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
25790 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
257a0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
257b0 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
257c0 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
257d0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
257e0 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
257f0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
25800 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
25810 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
25820 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
25830 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
25840 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
25850 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
25860 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
25870 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
25880 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
25890 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
258a0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
258b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
258c0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
258d0 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
258e0 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
258f0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
25900 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
25910 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
25920 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
25930 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
25940 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
25950 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
25960 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
25970 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
25980 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
25990 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
259a0 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
259b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
259c0 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
259d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
259e0 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
259f0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
25a00 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
25a10 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
25a20 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
25a30 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
25a40 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
25a50 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
25a60 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
25a70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
25a80 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
25a90 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
25aa0 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
25ab0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
25ac0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
25ad0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
25ae0 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
25af0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
25b00 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c  E flag..**.**  <
25b10 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a  li> <b>psow</b>:
25b20 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d   ^The psow param
25b30 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77  eter indicates w
25b40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
25b50 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73  e.**     [powers
25b60 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70  afe overwrite] p
25b70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20  roperty does or 
25b80 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74  does not apply t
25b90 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f  o the.**     sto
25ba0 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68  rage media on wh
25bb0 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ich the database
25bc0 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a   file resides..*
25bd0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f  *.**  <li> <b>no
25be0 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e  lock</b>: ^The n
25bf0 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20  olock parameter 
25c00 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
25c10 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  ry parameter.** 
25c20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74      which if set
25c30 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c   disables file l
25c40 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61  ocking in rollba
25c50 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73  ck journal modes
25c60 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69  .  This.**     i
25c70 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63  s useful for acc
25c80 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73  essing a databas
25c90 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65  e on a filesyste
25ca0 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a  m that does not.
25cb0 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c  **     support l
25cc0 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e  ocking.  Caution
25cd0 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72  :  Database corr
25ce0 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73  uption might res
25cf0 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20  ult if two.**   
25d00 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73    or more proces
25d10 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65  ses write to the
25d20 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61   same database a
25d30 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68  nd any one of th
25d40 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65  ose.**     proce
25d50 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b  sses uses nolock
25d60 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  =1..**.**  <li> 
25d70 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e  <b>immutable</b>
25d80 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65  : ^The immutable
25d90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
25da0 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a  boolean query.**
25db0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74       parameter t
25dc0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
25dd0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
25de0 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f  file is stored o
25df0 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e  n.**     read-on
25e00 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e  ly media.  ^When
25e10 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65   immutable is se
25e20 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  t, SQLite assume
25e30 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  s that the.**   
25e40 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20    database file 
25e50 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
25e60 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f  d, even by a pro
25e70 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72  cess with higher
25e80 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67  .**     privileg
25e90 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61  e, and so the da
25ea0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25eb0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61   read-only and a
25ec0 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20  ll locking.**   
25ed0 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74    and change det
25ee0 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c  ection is disabl
25ef0 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65  ed.  Caution: Se
25f00 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61  tting the immuta
25f10 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65  ble.**     prope
25f20 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73  rty on a databas
25f30 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73  e file that does
25f40 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20   in fact change 
25f50 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20  can result.**   
25f60 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71    in incorrect q
25f70 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64  uery results and
25f80 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  /or [SQLITE_CORR
25f90 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20  UPT] errors..** 
25fa0 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53      See also: [S
25fb0 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
25fc0 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20  TABLE]..**      
25fd0 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a   .** </ul>.**.**
25fe0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
25ff0 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
26000 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
26010 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
26020 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
26030 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
26040 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
26050 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
26060 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
26070 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
26080 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
26090 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
260a0 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
260b0 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
260c0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
260d0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
260e0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
260f0 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
26100 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
26110 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
26120 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
26130 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
26140 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
26150 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
26160 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
26170 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
26180 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
26190 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
261a0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
261b0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
261c0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
261d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
261e0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
261f0 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
26200 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
26210 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
26220 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
26230 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
26240 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
26250 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
26260 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
26270 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26280 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
26290 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
262a0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
262b0 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
262c0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
262d0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
262e0 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
262f0 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
26300 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
26310 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
26320 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
26330 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
26340 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
26350 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
26360 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
26370 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
26380 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
26390 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
263a0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
263b0 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
263c0 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
263d0 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
263e0 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
263f0 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
26400 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
26410 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
26420 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
26430 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
26440 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
26450 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
26460 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
26470 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
26480 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
26490 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
264a0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
264b0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
264c0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
264d0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
264e0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
264f0 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
26500 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
26510 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
26520 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
26530 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
26540 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
26550 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
26560 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
26570 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
26580 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
26590 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64  unix-dotfile <td
265a0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
265b0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
265c0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
265d0 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
265e0 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22  S "unix-dotfile"
265f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
26600 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73  t uses dot-files
26610 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73   in place of pos
26620 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b  ix advisory lock
26630 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ing..** <tr><td>
26640 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
26650 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
26660 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
26670 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
26680 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
26690 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
266a0 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
266b0 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
266c0 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
266d0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
266e0 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
266f0 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
26700 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
26710 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
26720 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
26730 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
26740 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
26750 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
26760 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
26770 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
26780 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
26790 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
267a0 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
267b0 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
267c0 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
267d0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
267e0 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
267f0 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
26800 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
26810 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
26820 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
26830 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
26840 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
26850 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
26860 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
26870 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
26880 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
26890 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
268a0 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
268b0 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
268c0 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
268d0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
268e0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
268f0 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
26900 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
26910 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
26920 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
26930 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
26940 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
26950 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
26960 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
26970 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
26980 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
26990 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
269a0 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
269b0 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
269c0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
269d0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
269e0 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
269f0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
26a00 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
26a10 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
26a20 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
26a30 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
26a40 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
26a50 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
26a60 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
26a70 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
26a80 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
26a90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
26aa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26ab0 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
26ac0 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
26ad0 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
26ae0 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
26af0 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
26b00 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
26b10 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
26b20 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
26b30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
26b40 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
26b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
26b60 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
26b70 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
26b80 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
26b90 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
26ba0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
26bb0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
26bc0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
26bd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
26be0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
26bf0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
26c00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
26c10 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
26c20 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
26c30 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
26c40 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
26c50 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
26c60 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
26c70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
26c80 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
26c90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26ca0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
26cb0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
26cc0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
26cd0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
26ce0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
26cf0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
26d00 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
26d10 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
26d20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
26d30 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
26d40 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
26d50 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
26d60 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
26d70 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
26d80 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
26d90 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
26da0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
26db0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
26dc0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
26dd0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
26de0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
26df0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
26e00 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
26e10 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
26e20 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
26e30 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
26e40 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
26e50 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
26e60 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
26e70 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
26e80 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
26e90 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
26ea0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
26eb0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
26ec0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
26ed0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
26ee0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
26ef0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
26f00 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
26f10 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
26f20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
26f30 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
26f40 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
26f50 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
26f60 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
26f70 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
26f80 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
26f90 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
26fa0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
26fb0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
26fc0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
26fd0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
26fe0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
26ff0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
27000 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
27010 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
27020 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
27030 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
27040 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
27050 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
27060 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
27070 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
27080 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
27090 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
270a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
270b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
270c0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
270d0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
270e0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
270f0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
27100 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
27110 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
27120 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
27130 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
27140 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
27150 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
27160 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
27170 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
27180 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
27190 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
271a0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
271b0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
271c0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
271d0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
271e0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
271f0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
27200 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27210 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27220 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
27230 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
27240 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
27250 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
27260 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
27270 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
27280 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
27290 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
272a0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
272b0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
272c0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
272d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
272e0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
272f0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
27300 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
27310 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
27320 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
27330 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27340 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
27350 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27360 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
27370 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
27380 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
27390 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
273a0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
273b0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
273c0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
273d0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
273e0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
273f0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
27400 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
27410 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
27420 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
27430 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
27440 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
27450 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
27460 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
27470 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
27480 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
27490 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
274a0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
274b0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
274c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
274d0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
274e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
274f0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
27500 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
27510 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
27520 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
27530 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
27540 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
27550 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
27560 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
27570 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
27580 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
27590 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
275a0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  ALL sqlite3_uri_
275b0 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
275c0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
275d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
275e0 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ram);.SQLITE_API
275f0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
27600 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  ALL sqlite3_uri_
27610 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
27620 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
27630 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
27640 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51  nt bDefault);.SQ
27650 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
27660 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
27670 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72  DCALL sqlite3_ur
27680 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
27690 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
276a0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
276b0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
276c0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
276d0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20  And Messages.** 
276e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
276f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
27700 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65  st recent sqlite
27710 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73  3_* API call ass
27720 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
27730 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27740 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c  ction] D failed,
27750 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
27760 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74  3_errcode(D) int
27770 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
27780 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
27790 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
277a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
277b0 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a  code] for that.*
277c0 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49  * API call..** I
277d0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
277e0 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73  t API call was s
277f0 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68  uccessful,.** th
27800 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
27810 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
27820 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
27830 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  defined..** ^The
27840 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
27850 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
27860 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
27870 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
27880 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
27890 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
278a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
278b0 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
278c0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
278d0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
278e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
278f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
27900 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
27910 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
27920 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
27930 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
27940 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
27950 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
27960 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
27970 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
27980 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
27990 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
279a0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
279b0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
279c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
279d0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
279e0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
279f0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
27a00 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
27a10 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
27a20 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
27a30 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
27a40 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
27a50 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
27a60 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
27a70 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
27a80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27a90 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
27aa0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
27ab0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
27ac0 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
27ad0 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
27ae0 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
27af0 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
27b00 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
27b10 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
27b20 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
27b30 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
27b40 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
27b50 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
27b60 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
27b70 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
27b80 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
27b90 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
27ba0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
27bb0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
27bc0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
27bd0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
27be0 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
27bf0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
27c00 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
27c10 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
27c20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
27c30 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
27c40 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
27c50 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
27c60 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
27c70 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
27c80 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
27c90 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
27ca0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
27cb0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
27cc0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
27cd0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
27ce0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
27cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
27d00 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
27d10 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
27d20 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
27d30 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
27d40 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
27d50 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
27d60 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
27d70 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
27d80 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
27d90 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
27da0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
27db0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
27dc0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
27dd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
27de0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
27df0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
27e00 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
27e10 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
27e20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
27e30 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
27e40 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
27e50 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
27e60 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
27e70 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
27e80 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
27e90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
27ea0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
27eb0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
27ec0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
27ed0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
27ee0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
27ef0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
27f00 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
27f10 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  b);.SQLITE_API c
27f20 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
27f30 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
27f40 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
27f50 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
27f60 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
27f70 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
27f80 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
27f90 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
27fa0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
27fb0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
27fc0 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
27fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27fe0 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
27ff0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
28000 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
28010 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
28020 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28030 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
28040 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
28050 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
28060 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
28070 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
28080 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
28090 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
280a0 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
280b0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
280c0 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
280d0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
280e0 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
280f0 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
28100 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
28110 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
28120 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
28130 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28140 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
28150 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
28160 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
28170 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
28180 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
28190 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
281a0 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
281b0 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
281c0 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
281d0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
281e0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
281f0 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
28200 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
28210 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
28220 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28230 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
28240 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
28250 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
28260 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
28270 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
28280 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28290 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
282a0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
282b0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
282c0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
282d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
282e0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
282f0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
28300 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
28310 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
28320 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
28330 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
28340 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
28350 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
28360 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
28370 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
28380 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
28390 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
283a0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
283b0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
283c0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
283d0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
283e0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
283f0 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
28400 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
28410 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
28420 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
28430 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
28440 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
28450 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
28460 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
28470 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
28480 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
28490 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
284a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
284b0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
284c0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
284d0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
284e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
284f0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
28500 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
28510 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
28520 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
28530 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
28540 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
28550 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28560 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
28570 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
28580 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
28590 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
285a0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
285b0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
285c0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
285d0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
285e0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
285f0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
28600 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
28610 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
28620 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
28630 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
28640 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
28650 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
28660 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
28670 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
28680 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
28690 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
286a0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
286b0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
286c0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
286d0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
286e0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
286f0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
28700 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
28710 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
28720 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
28730 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
28740 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
28750 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
28760 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
28770 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
28780 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
28790 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
287a0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
287b0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
287c0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
287d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
287e0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
287f0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
28800 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
28810 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
28820 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
28830 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
28840 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
28850 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
28860 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
28870 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
28880 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
28890 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
288a0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
288b0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
288c0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
288d0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
288e0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
288f0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
28900 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
28910 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
28920 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
28930 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
28940 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
28950 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
28960 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
28970 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
28980 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
28990 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
289a0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
289b0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
289c0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
289d0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
289e0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
289f0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
28a00 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
28a10 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
28a20 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
28a30 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
28a40 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
28a50 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
28a60 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
28a70 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
28a80 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
28a90 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
28aa0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
28ab0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
28ac0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
28ad0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
28ae0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
28af0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
28b00 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
28b10 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
28b20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
28b30 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
28b40 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
28b50 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
28b60 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
28b70 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
28b80 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
28b90 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
28ba0 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
28bb0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
28bc0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69  DCALL sqlite3_li
28bd0 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
28be0 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
28bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28c00 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
28c10 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
28c20 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
28c30 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
28c40 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
28c50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
28c60 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
28c70 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
28c80 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
28c90 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
28ca0 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
28cb0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28cc0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
28cd0 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
28ce0 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
28cf0 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
28d00 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
28d10 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
28d20 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
28d30 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
28d40 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
28d50 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
28d60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
28d70 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
28d80 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
28d90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28da0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
28db0 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
28dc0 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
28dd0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
28de0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28df0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
28e00 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
28e10 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
28e20 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
28e30 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
28e40 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
28e50 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
28e60 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
28e70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
28e80 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
28e90 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
28ea0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
28eb0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
28ec0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
28ed0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
28ee0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
28ef0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
28f00 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
28f10 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
28f20 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
28f30 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
28f40 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
28f50 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
28f60 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28f70 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
28f80 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
28f90 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
28fa0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
28fb0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
28fc0 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
28fd0 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
28fe0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
28ff0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29000 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
29010 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29020 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
29030 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
29040 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
29050 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
29060 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
29070 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
29080 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
29090 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
290a0 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
290b0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
290c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
290d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
290e0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
290f0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
29100 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
29110 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
29120 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
29130 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
29140 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
29150 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
29160 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
29170 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
29180 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
29190 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
291a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
291b0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
291c0 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
291d0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
291e0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
291f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29200 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
29210 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
29220 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29230 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
29240 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
29250 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
29260 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
29270 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29280 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
29290 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
292a0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
292b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
292c0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
292d0 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
292e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
292f0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
29300 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29310 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
29320 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
29330 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
29340 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
29350 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
29360 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29370 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
29380 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
29390 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
293a0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
293b0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
293c0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
293d0 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
293e0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
293f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
29400 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29410 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29420 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
29430 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
29440 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
29450 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29460 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
29470 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
29480 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29490 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
294a0 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28  KER_THREADS]] ^(
294b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
294c0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c  _WORKER_THREADS<
294d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
294e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
294f0 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b  f auxiliary work
29500 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
29510 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65  a single.** [pre
29520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29530 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e   may start.</dd>
29540 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
29550 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29560 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
29570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
29580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29590 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
295a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
295b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
295c0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
295d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
295e0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
295f0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
29600 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
29610 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
29620 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
29630 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
29640 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
29650 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
29660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29670 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
29680 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
29690 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
296a0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
296b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
296c0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
296d0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
296e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
296f0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
29700 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
29710 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29720 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
29730 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
29740 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
29750 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
29760 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
29770 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  e SQLITE_LIMIT_W
29780 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20  ORKER_THREADS   
29790 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a          11../*.*
297a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
297b0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
297c0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
297d0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
297e0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
297f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
29800 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
29810 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
29820 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
29830 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
29840 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
29850 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
29860 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
29870 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
29880 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
29890 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
298a0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
298b0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
298c0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
298d0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
298e0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
298f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
29900 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
29910 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
29920 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
29930 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
29940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
29950 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
29960 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
29970 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
29980 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
29990 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
299a0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
299b0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
299c0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
299d0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
299e0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
299f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29a00 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
29a10 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
29a20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29a30 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
29a40 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
29a50 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
29a60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
29a70 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e  te argument is n
29a80 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53  egative, then zS
29a90 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
29aa0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
29ab0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
29ac0 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69  If nByte is posi
29ad0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
29ae0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
29af0 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  f bytes read fro
29b00 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79  m zSql.  ^If nBy
29b10 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  te is zero, then
29b20 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20   no prepared.** 
29b30 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e  statement is gen
29b40 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68  erated..** If th
29b50 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74  e caller knows t
29b60 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
29b70 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
29b80 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a  erminated, then.
29b90 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  ** there is a sm
29ba0 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  all performance 
29bb0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73  advantage to pas
29bc0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
29bd0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
29be0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
29bf0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
29c00 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
29c10 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
29c20 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
29c30 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  r..**.** ^If pzT
29c40 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
29c50 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
29c60 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
29c70 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
29c80 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
29c90 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
29ca0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
29cb0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
29cc0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
29cd0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
29ce0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
29cf0 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
29d00 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
29d10 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
29d20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
29d30 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
29d40 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
29d50 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
29d60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
29d70 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
29d80 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
29d90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
29da0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
29db0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
29dc0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
29dd0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
29de0 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
29df0 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
29e00 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
29e10 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
29e20 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
29e30 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
29e40 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
29e50 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
29e60 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
29e70 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
29e80 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
29e90 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
29ea0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29eb0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
29ec0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
29ed0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
29ee0 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
29ef0 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
29f00 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
29f10 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
29f20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29f30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
29f40 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
29f50 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
29f60 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
29f70 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29f80 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
29f90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
29fa0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
29fb0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
29fc0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
29fd0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
29fe0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
29ff0 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
2a000 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
2a010 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
2a020 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
2a030 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
2a040 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2a050 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
2a060 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
2a070 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
2a080 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2a090 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
2a0a0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
2a0b0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2a0c0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
2a0d0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
2a0e0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
2a0f0 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
2a100 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
2a110 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
2a120 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
2a130 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2a140 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
2a150 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
2a160 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2a170 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
2a180 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
2a190 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
2a1a0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
2a1b0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2a1c0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
2a1d0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
2a1e0 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
2a1f0 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49  As many as [SQLI
2a200 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45  TE_MAX_SCHEMA_RE
2a210 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20  TRY].** retries 
2a220 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72  will occur befor
2a230 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2a240 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65   gives up and re
2a250 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a  turns an error..
2a260 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2a270 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
2a280 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
2a290 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2a2a0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
2a2b0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
2a2c0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
2a2d0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2a2e0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
2a2f0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
2a300 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
2a310 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
2a320 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
2a330 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
2a340 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
2a350 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
2a360 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
2a370 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
2a380 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
2a390 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a3a0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
2a3b0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
2a3c0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
2a3d0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
2a3e0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
2a3f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
2a400 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
2a410 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
2a420 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
2a430 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
2a440 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
2a450 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
2a460 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
2a470 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
2a480 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
2a490 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
2a4a0 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
2a4b0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
2a4c0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2a4d0 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
2a4e0 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
2a4f0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2a500 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2a510 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
2a520 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
2a530 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
2a540 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
2a550 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
2a560 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
2a570 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
2a580 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2a590 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
2a5a0 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
2a5b0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
2a5c0 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
2a5d0 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
2a5e0 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
2a5f0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2a600 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
2a610 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
2a620 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2a630 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
2a640 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
2a650 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
2a660 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
2a670 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
2a680 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
2a690 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
2a6a0 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
2a6b0 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
2a6c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2a6d0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c  is enabled..** <
2a6e0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
2a6f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a700 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2a710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
2a720 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2a730 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2a740 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2a750 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2a760 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2a770 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2a780 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2a790 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2a7a0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2a7b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2a7c0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2a7d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2a7e0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2a7f0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2a800 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2a810 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2a820 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2a830 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2a840 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
2a850 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2a860 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2a870 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
2a880 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2a890 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2a8a0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2a8b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2a8c0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2a8d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2a8e0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2a8f0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2a900 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2a910 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2a920 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2a930 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2a940 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2a950 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2a960 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2a970 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2a980 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2a990 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2a9a0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
2a9b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2a9c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2a9d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
2a9e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2a9f0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2aa00 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2aa10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2aa20 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2aa30 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2aa40 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2aa50 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2aa60 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2aa70 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2aa80 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2aa90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2aaa0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2aab0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2aac0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2aad0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2aae0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2aaf0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2ab00 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
2ab10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2ab20 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2ab30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ab40 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ab50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ab60 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2ab70 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2ab80 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2ab90 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2aba0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2abb0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2abc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2abd0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2abe0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2abf0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2ac00 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ac10 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2ac20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2ac30 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2ac40 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2ac50 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2ac60 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2ac70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac80 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
2ac90 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45  tement SQL.** ME
2aca0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2acb0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2acc0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74  lite3_sql(P) int
2acd0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2ace0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
2acf0 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a  py of the UTF-8.
2ad00 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
2ad10 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70   to create [prep
2ad20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ad30 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72  P if P was.** cr
2ad40 65 61 74 65 64 20 62 79 20 65 69 74 68 65 72 20  eated by either 
2ad50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ad60 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2ad70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ad80 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
2ad90 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2ada0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2adb0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2adc0 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74  to a UTF-8.** st
2add0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
2ade0 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20  the SQL text of 
2adf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ae00 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f  nt P with.** [bo
2ae10 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20  und parameters] 
2ae20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  expanded..**.** 
2ae30 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2ae40 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2ae50 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65  tement is create
2ae60 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a  d using the SQL.
2ae70 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20  ** text "SELECT 
2ae80 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69  $abc,:xyz" and i
2ae90 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63  f parameter $abc
2aea0 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74   is bound to int
2aeb0 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64  eger 2345.** and
2aec0 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20   parameter :xyz 
2aed0 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e  is unbound, then
2aee0 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77   sqlite3_sql() w
2aef0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  ill return.** th
2af00 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e  e original strin
2af10 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  g, "SELECT $abc,
2af20 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65  :xyz" but sqlite
2af30 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2af40 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2af50 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c  "SELECT 2345,NUL
2af60 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  L".)^.**.** ^The
2af70 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2af80 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63  d_sql() interfac
2af90 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
2afa0 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
2afb0 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69  emory.** is avai
2afc0 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68  lable to hold th
2afd0 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20  e result, or if 
2afe0 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64  the result would
2aff0 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74   exceed the.** t
2b000 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e  he maximum strin
2b010 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69  g length determi
2b020 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49  ned by the [SQLI
2b030 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2b040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
2b050 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
2b060 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
2b070 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74  ime option limit
2b080 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
2b090 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
2b0a0 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54   expansions.  ^T
2b0b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2b0c0 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
2b0d0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61  ime.** option ca
2b0e0 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70  uses sqlite3_exp
2b0f0 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61  anded_sql() to a
2b100 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c  lways return NUL
2b110 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74  L..**.** ^The st
2b120 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2b130 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2b140 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51  is managed by SQ
2b150 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61  Lite and is.** a
2b160 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2b170 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70  ed when the prep
2b180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2b190 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  s finalized..** 
2b1a0 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  ^The string retu
2b1b0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2b1c0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c  expanded_sql(P),
2b1d0 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61   on the other ha
2b1e0 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e  nd,.** is obtain
2b1f0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2b200 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d  _malloc()] and m
2b210 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74  ust be free by t
2b220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
2b230 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20  * by passing it 
2b240 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
2b250 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2b260 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2b270 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2b280 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2b290 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2b2a0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
2b2b0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2b2c0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2b2d0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2b2e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2b2f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2b300 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
2b310 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
2b320 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
2b330 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b340 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2b350 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2b360 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
2b370 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2b380 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
2b390 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
2b3a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b3b0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
2b3c0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
2b3d0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
2b3e0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2b3f0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
2b400 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
2b410 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2b420 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
2b430 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
2b440 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
2b450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
2b460 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
2b470 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
2b480 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2b490 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2b4a0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
2b4b0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
2b4c0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
2b4d0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
2b4e0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
2b4f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
2b500 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
2b510 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2b520 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
2b530 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
2b540 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
2b550 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
2b560 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
2b570 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
2b580 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2b590 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
2b5a0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
2b5b0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
2b5c0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2b5d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
2b5e0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
2b5f0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2b600 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
2b610 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
2b620 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
2b630 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
2b640 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
2b650 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
2b660 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
2b670 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
2b680 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
2b690 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2b6a0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
2b6b0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
2b6c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
2b6d0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
2b6e0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
2b6f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
2b700 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
2b710 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
2b720 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
2b730 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
2b740 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
2b750 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
2b760 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
2b770 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
2b780 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
2b790 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2b7a0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2b7b0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
2b7c0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
2b7d0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
2b7e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
2b7f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2b800 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
2b810 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
2b820 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
2b830 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2b840 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
2b850 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2b860 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2b870 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  L sqlite3_stmt_r
2b880 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
2b890 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2b8a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b8b0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
2b8c0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2b8d0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
2b8e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2b8f0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2b900 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2b910 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
2b920 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2b930 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
2b940 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b950 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
2b960 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
2b970 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
2b980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2b990 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65  p(S)] but has ne
2b9a0 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d  ither run to com
2b9b0 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65  pletion (returne
2b9c0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d.** [SQLITE_DON
2b9d0 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  E] from [sqlite3
2b9e0 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a  _step(S)]) nor.*
2b9f0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
2ba00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2ba10 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
2ba20 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
2ba30 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2ba40 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
2ba50 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
2ba60 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
2ba70 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
2ba80 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
2ba90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
2baa0 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
2bab0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2bac0 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
2bad0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2bae0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2baf0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
2bb00 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2bb10 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
2bb20 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
2bb30 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2bb40 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
2bb50 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
2bb60 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
2bb70 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
2bb80 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
2bb90 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
2bba0 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
2bbb0 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
2bbc0 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
2bbd0 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
2bbe0 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
2bbf0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
2bc00 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
2bc10 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
2bc20 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
2bc30 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49  on open..*/.SQLI
2bc40 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2bc50 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2bc60 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
2bc70 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2bc80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
2bc90 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
2bca0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
2bcb0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
2bcc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bcd0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
2bce0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
2bcf0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
2bd00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
2bd10 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
2bd20 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
2bd30 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
2bd40 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
2bd50 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
2bd60 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2bd70 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
2bd80 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
2bd90 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
2bda0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
2bdb0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
2bdc0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
2bdd0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
2bde0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
2bdf0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
2be00 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
2be10 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2be20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
2be30 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
2be40 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
2be50 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
2be60 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
2be70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2be80 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
2be90 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
2bea0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
2beb0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
2bec0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2bed0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
2bee0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
2bef0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
2bf00 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
2bf10 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
2bf20 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
2bf30 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
2bf40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2bf50 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2bf60 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
2bf70 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2bf80 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
2bf90 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
2bfa0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2bfb0 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
2bfc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bfd0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
2bfe0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
2bff0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
2c000 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
2c010 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
2c020 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
2c030 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
2c040 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2c050 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
2c060 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c070 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
2c080 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
2c090 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2c0a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2c0b0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
2c0c0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
2c0d0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
2c0e0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
2c0f0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
2c100 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
2c110 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2c120 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
2c130 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
2c140 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
2c150 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
2c160 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
2c170 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
2c180 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
2c190 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2c1a0 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
2c1b0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
2c1c0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2c1d0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2c1e0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2c1f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
2c200 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
2c210 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
2c220 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
2c230 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
2c240 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
2c250 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
2c260 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
2c270 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
2c280 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
2c290 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2c2a0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2c2b0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2c2c0 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
2c2d0 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
2c2e0 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
2c2f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c300 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
2c310 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
2c320 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
2c330 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
2c340 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
2c350 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2c360 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
2c370 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
2c380 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2c390 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
2c3a0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2c3b0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2c3c0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
2c3d0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
2c3e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c3f0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
2c400 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
2c410 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c420 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2c430 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2c440 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2c450 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2c460 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2c470 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2c480 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2c490 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2c4a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2c4b0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2c4c0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
2c4d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
2c4e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2c4f0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
2c500 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
2c510 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
2c520 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
2c530 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
2c540 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
2c550 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
2c560 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
2c570 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
2c580 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2c590 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
2c5a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2c5b0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
2c5c0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c5d0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
2c5e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c5f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2c600 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2c610 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
2c620 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
2c630 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
2c640 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2c650 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
2c660 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
2c670 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2c680 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
2c690 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
2c6a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2c6b0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2c6c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
2c6d0 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
2c6e0 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
2c6f0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
2c700 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2c710 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2c720 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2c730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c740 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
2c750 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
2c760 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
2c770 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
2c780 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
2c790 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
2c7a0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
2c7b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2c7c0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
2c7d0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
2c7e0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
2c7f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c800 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c810 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2c820 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2c830 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2c840 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2c850 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2c860 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2c870 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2c880 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2c890 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2c8a0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2c8b0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2c8c0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2c8d0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2c8e0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2c8f0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2c900 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2c910 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2c920 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2c930 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2c940 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2c950 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2c960 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2c970 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2c980 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2c990 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2c9a0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2c9b0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2c9c0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2c9d0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2c9e0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2c9f0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2ca00 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2ca10 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2ca20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2ca30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2ca40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ca50 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2ca60 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2ca70 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ca80 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2ca90 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2caa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2cab0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2cac0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2cad0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2cae0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2caf0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2cb00 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2cb10 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2cb20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2cb30 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2cb40 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2cb50 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2cb60 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2cb70 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2cb80 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2cb90 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2cba0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2cbb0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2cbc0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2cbd0 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2cbe0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2cbf0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2cc00 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2cc10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2cc20 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2cc30 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2cc40 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2cc50 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2cc60 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2cc70 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2cc80 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2cc90 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2cca0 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2ccb0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2ccc0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2ccd0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2cce0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2ccf0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2cd00 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2cd10 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2cd20 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2cd30 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2cd40 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2cd50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2cd60 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2cd70 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2cd80 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
2cd90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2cda0 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
2cdb0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
2cdc0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
2cdd0 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
2cde0 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
2cdf0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2ce00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2ce10 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
2ce20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2ce30 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2ce40 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2ce50 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2ce60 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ce70 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2ce80 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2ce90 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2cea0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2ceb0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2cec0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2ced0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2cee0 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2cef0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2cf00 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2cf10 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2cf20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2cf30 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
2cf40 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
2cf50 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
2cf60 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
2cf70 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
2cf80 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2cf90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2cfa0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
2cfb0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2cfc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2cfd0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2cfe0 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
2cff0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2d000 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
2d010 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
2d020 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
2d030 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
2d040 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
2d050 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2d060 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
2d070 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
2d080 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
2d090 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
2d0a0 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
2d0b0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
2d0c0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
2d0d0 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
2d0e0 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
2d0f0 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
2d100 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
2d110 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
2d120 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
2d130 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
2d140 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
2d150 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
2d160 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
2d170 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
2d180 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
2d190 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
2d1a0 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
2d1b0 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
2d1c0 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
2d1d0 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
2d1e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2d1f0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
2d200 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
2d210 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
2d220 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
2d230 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
2d240 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
2d250 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2d260 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
2d270 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
2d280 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2d290 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
2d2a0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
2d2b0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2d2c0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2d2d0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
2d2e0 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69   to bind API fai
2d2f0 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ls..** ^If the f
2d300 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
2d310 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
2d320 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
2d330 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
2d340 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2d350 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
2d360 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
2d370 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
2d380 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
2d390 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
2d3a0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2d3b0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
2d3c0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
2d3d0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
2d3e0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
2d3f0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2d400 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
2d410 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
2d420 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
2d430 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2d440 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
2d450 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
2d460 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2d470 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2d480 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
2d490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2d4a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2d4b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2d4c0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
2d4d0 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
2d4e0 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
2d4f0 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
2d500 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
2d510 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
2d520 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2d530 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2d540 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
2d550 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
2d560 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
2d570 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
2d580 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
2d590 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
2d5a0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
2d5b0 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
2d5c0 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
2d5d0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
2d5e0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
2d5f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2d600 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2d610 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
2d620 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
2d630 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
2d640 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
2d650 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
2d660 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
2d670 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
2d680 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
2d690 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
2d6a0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
2d6b0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
2d6c0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
2d6d0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
2d6e0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
2d6f0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
2d700 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
2d710 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
2d720 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
2d730 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2d740 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
2d750 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
2d760 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
2d770 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
2d780 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
2d790 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
2d7a0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
2d7b0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
2d7c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d7d0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
2d7e0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
2d7f0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
2d800 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2d810 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
2d820 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
2d830 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
2d840 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
2d850 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
2d860 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
2d870 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
2d880 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
2d890 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
2d8a0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
2d8b0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
2d8c0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
2d8d0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
2d8e0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
2d8f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2d900 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
2d910 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
2d920 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2d930 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2d940 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
2d950 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
2d960 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
2d970 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d980 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
2d990 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
2d9a0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
2d9b0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
2d9c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2d9d0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
2d9e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2d9f0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
2da00 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
2da10 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
2da20 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
2da30 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
2da40 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2da50 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
2da60 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
2da70 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
2da80 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
2da90 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2daa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2dab0 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
2dac0 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
2dad0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
2dae0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2daf0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
2db00 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
2db10 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
2db20 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
2db30 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
2db40 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
2db50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2db60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2db70 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
2db80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2db90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2dba0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2dbb0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2dbc0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2dbd0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2dbe0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2dbf0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2dc00 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2dc10 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2dc20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2dc30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2dc40 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2dc50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2dc60 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2dc70 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2dc80 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
2dc90 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2dca0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2dcb0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2dcc0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2dcd0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2dce0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2dcf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2dd00 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  t, double);.SQLI
2dd10 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2dd20 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2dd30 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
2dd40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2dd50 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2dd60 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2dd70 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2dd80 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2dd90 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2dda0 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
2ddb0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2ddc0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2ddd0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
2dde0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53  3_stmt*, int);.S
2ddf0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2de00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2de10 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2de20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2de30 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2de40 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2de50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2de60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2de70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2de80 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2de90 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2dea0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2deb0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2dec0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2ded0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2dee0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
2def0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2df00 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
2df10 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2df20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2df30 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2df40 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
2df50 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
2df60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2df70 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2df80 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2df90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2dfa0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2dfb0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2dfc0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2dfd0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2dfe0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2dff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e000 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49  nt, int n);.SQLI
2e010 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2e020 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2e030 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2e040 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2e050 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2e060 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2e070 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2e080 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2e090 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e0a0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e0b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2e0c0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2e0d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2e0e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2e0f0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2e100 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2e110 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2e120 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2e130 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2e140 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2e150 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2e160 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2e170 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2e180 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2e190 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e1a0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2e1b0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2e1c0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2e1d0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2e1e0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2e1f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2e200 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2e210 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2e220 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2e230 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2e240 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2e250 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2e260 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2e270 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2e280 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2e290 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2e2a0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2e2b0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2e2c0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2e2d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e2e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e2f0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2e300 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e310 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e320 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2e330 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e340 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e350 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e360 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2e370 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2e380 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2e390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2e3a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e3b0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2e3c0 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
2e3d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e3e0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2e3f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2e400 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2e410 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2e420 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2e430 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2e440 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2e450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e460 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2e470 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2e480 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2e490 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2e4a0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2e4b0 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2e4c0 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2e4d0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2e4e0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2e4f0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2e500 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2e510 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2e520 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2e530 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2e540 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2e550 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2e560 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2e570 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2e580 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2e590 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2e5a0 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2e5b0 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2e5c0 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2e5d0 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2e5e0 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2e5f0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2e600 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2e610 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2e620 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2e630 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2e640 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2e650 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2e660 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2e670 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2e680 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2e690 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2e6a0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2e6b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2e6c0 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2e6d0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2e6e0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2e6f0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2e700 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2e710 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2e720 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e730 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2e740 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e750 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2e760 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2e770 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2e780 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2e790 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2e7a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e7b0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2e7c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2e7d0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
2e7e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2e7f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2e800 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2e810 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2e820 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2e830 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2e840 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2e850 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2e860 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2e870 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2e880 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2e890 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2e8a0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2e8b0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2e8c0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2e8d0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2e8e0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2e8f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2e900 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2e910 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2e920 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2e930 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2e940 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2e950 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2e960 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2e970 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2e980 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2e990 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2e9a0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2e9b0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2e9c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2e9d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2e9e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e9f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ea00 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2ea10 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2ea20 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ea30 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2ea40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ea50 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2ea60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2ea70 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2ea80 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2ea90 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2eaa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
2eab0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2eac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ead0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
2eae0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
2eaf0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2eb00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2eb10 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  3_stmt.**.** ^Co
2eb20 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2eb30 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2eb40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2eb50 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2eb60 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2eb70 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2eb80 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2eb90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2eba0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2ebb0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2ebc0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2ebd0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2ebe0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ebf0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2ec00 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2ec10 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2ec20 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2ec30 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2ec40 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2ec50 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2ec60 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ec70 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2ec80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2ec90 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2eca0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2ecb0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2ecc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2ecd0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
2ece0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
2ecf0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
2ed00 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
2ed10 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
2ed20 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2ed30 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
2ed40 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2ed50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2ed60 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2ed70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2ed80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2ed90 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2eda0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2edb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2edc0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2edd0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2ede0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2edf0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2ee00 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2ee10 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2ee20 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2ee30 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2ee40 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2ee50 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2ee60 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2ee70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2ee80 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2ee90 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2eea0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2eeb0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2eec0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2eed0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2eee0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2eef0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2ef00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2ef10 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2ef20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2ef30 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2ef40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ef50 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2ef60 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2ef70 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2ef80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ef90 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2efa0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2efb0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2efc0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2efd0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2efe0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2eff0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2f000 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2f010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2f020 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2f030 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2f040 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2f050 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2f060 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2f070 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2f080 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2f090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2f0a0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2f0b0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2f0c0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2f0d0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2f0e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2f0f0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2f100 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2f110 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2f120 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2f130 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2f140 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2f150 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2f160 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2f170 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2f180 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2f190 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2f1a0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2f1b0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2f1c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f1d0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2f1e0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2f1f0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2f200 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2f210 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2f220 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2f230 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2f240 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2f250 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2f260 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2f270 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2f280 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2f290 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2f2a0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2f2b0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54  e next..*/.SQLIT
2f2c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2f2d0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2f2e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f2f0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2f300 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49  t*, int N);.SQLI
2f310 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2f320 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
2f330 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f340 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2f350 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2f360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f370 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2f380 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2f390 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f3a0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f3b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2f3c0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2f3d0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2f3e0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2f3f0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2f400 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2f410 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2f420 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2f430 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2f440 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2f450 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2f460 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2f470 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2f480 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2f490 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2f4a0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2f4b0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2f4c0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2f4d0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2f4e0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2f4f0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2f500 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2f510 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2f520 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2f530 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2f540 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2f550 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2f560 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2f570 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2f580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2f590 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2f5a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2f5b0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2f5c0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2f5d0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2f5e0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2f5f0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2f600 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2f610 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2f620 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2f630 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2f640 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2f650 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2f660 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2f670 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2f680 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2f690 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2f6a0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2f6b0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2f6c0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2f6d0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2f6e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2f6f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2f700 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2f710 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f720 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2f730 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2f740 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2f750 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2f760 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2f770 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2f780 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2f790 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2f7a0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2f7b0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2f7c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2f7d0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2f7e0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2f7f0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2f800 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2f810 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2f820 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2f830 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2f840 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2f850 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2f860 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2f870 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2f880 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2f890 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2f8a0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2f8b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2f8c0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2f8d0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2f8e0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2f8f0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2f900 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2f910 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2f920 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2f930 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2f940 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2f950 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2f960 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2f970 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2f980 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2f990 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2f9a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2f9b0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2f9c0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2f9d0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2f9e0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2f9f0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2fa00 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2fa10 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2fa20 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2fa30 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2fa40 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2fa50 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2fa60 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2fa70 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2fa80 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2fa90 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2faa0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2fab0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2fac0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2fad0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2fae0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2faf0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2fb00 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2fb10 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2fb20 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2fb30 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2fb40 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2fb50 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2fb60 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2fb70 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2fb80 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2fb90 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2fba0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2fbb0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2fbc0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2fbd0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2fbe0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2fbf0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2fc00 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2fc10 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2fc20 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2fc30 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2fc40 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2fc50 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2fc60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2fc70 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2fc80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2fc90 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2fca0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2fcb0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2fcc0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2fcd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2fce0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2fcf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2fd00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2fd10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2fd20 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2fd30 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2fd40 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2fd50 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2fd60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fd70 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2fd80 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2fd90 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2fda0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2fdb0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2fdc0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2fdd0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2fde0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2fdf0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2fe00 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2fe10 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2fe20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2fe30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
2fe40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2fe50 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2fe60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2fe70 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2fe80 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2fe90 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2fea0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2feb0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2fec0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2fed0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2fee0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2fef0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2ff00 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2ff10 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2ff20 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2ff30 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2ff40 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2ff50 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2ff60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2ff70 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2ff80 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2ff90 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2ffa0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2ffb0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2ffc0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2ffd0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2ffe0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2fff0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
30000 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
30010 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
30020 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
30030 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
30040 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
30050 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
30060 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
30070 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
30080 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
30090 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
300a0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
300b0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
300c0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
300d0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
300e0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
300f0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
30100 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
30110 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
30120 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
30130 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
30140 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
30150 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
30160 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
30170 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
30180 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
30190 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
301a0 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
301b0 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
301c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
301d0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
301e0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
301f0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
30200 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
30210 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
30220 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
30230 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
30240 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
30250 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
30260 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
30270 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
30280 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53  ose values..*/.S
30290 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
302a0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
302b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
302c0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
302d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
302e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
302f0 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
30300 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
30310 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
30320 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30330 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
30340 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
30350 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
30360 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30370 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
30380 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
30390 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
303a0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
303b0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
303c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
303d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
303e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
303f0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
30400 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
30410 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
30420 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
30430 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
30440 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
30450 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
30460 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
30470 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
30480 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
30490 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
304a0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
304b0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
304c0 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
304d0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
304e0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
304f0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
30500 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
30510 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
30520 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
30530 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
30540 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30550 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
30560 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
30570 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
30580 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
30590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
305a0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
305b0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
305c0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
305d0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
305e0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
305f0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
30600 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
30610 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
30620 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
30630 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
30640 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
30650 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
30660 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
30670 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
30680 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
30690 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
306a0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
306b0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
306c0 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
306d0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
306e0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
306f0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
30700 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
30710 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
30720 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
30730 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
30740 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
30750 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
30760 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
30770 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
30780 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
30790 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
307a0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
307b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
307c0 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
307d0 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
307e0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
307f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
30800 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
30810 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
30820 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
30830 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
30840 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
30850 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
30860 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
30870 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
30880 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
30890 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
308a0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
308b0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
308c0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
308d0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
308e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
308f0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
30900 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
30910 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
30920 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
30930 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
30940 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
30950 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
30960 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
30970 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
30980 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
30990 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
309a0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
309b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
309c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
309d0 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
309e0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
309f0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
30a00 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
30a10 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
30a20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
30a30 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
30a40 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
30a50 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
30a60 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
30a70 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
30a80 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
30a90 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
30aa0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
30ab0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
30ac0 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
30ad0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
30ae0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
30af0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
30b00 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
30b10 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
30b20 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
30b30 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
30b40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
30b50 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
30b60 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
30b70 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
30b80 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
30b90 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
30ba0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
30bb0 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
30bc0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
30bd0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
30be0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
30bf0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
30c00 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
30c10 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
30c20 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
30c30 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
30c40 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
30c50 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
30c60 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
30c70 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
30c80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30c90 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
30ca0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
30cb0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
30cc0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
30cd0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
30ce0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
30cf0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
30d00 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
30d10 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
30d20 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
30d30 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
30d40 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
30d50 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
30d60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30d70 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
30d80 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
30d90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30da0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
30db0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
30dc0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
30dd0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
30de0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
30df0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
30e00 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
30e10 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
30e20 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
30e30 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
30e40 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
30e50 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
30e60 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
30e70 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
30e80 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
30e90 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
30ea0 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
30eb0 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
30ec0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
30ed0 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
30ee0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
30ef0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
30f00 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
30f10 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
30f20 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
30f30 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
30f40 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
30f50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
30f60 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
30f70 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
30f80 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
30f90 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
30fa0 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
30fb0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
30fc0 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
30fd0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
30fe0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
30ff0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
31000 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
31010 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
31020 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
31030 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
31040 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
31050 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
31060 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
31070 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
31080 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
31090 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
310a0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
310b0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
310c0 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
310d0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
310e0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
310f0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
31100 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
31110 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
31120 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
31130 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
31140 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
31150 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
31160 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
31170 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
31180 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
31190 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
311a0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
311b0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
311c0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
311d0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
311e0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
311f0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
31200 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
31210 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
31220 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
31230 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
31240 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
31250 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
31260 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
31270 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
31280 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
31290 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
312a0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
312b0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
312c0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
312d0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
312e0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
312f0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
31300 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
31310 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
31320 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
31330 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
31340 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
31350 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
31360 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
31370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31380 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
31390 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
313a0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
313b0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
313c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
313d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
313e0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
313f0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
31400 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
31410 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
31420 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
31430 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
31440 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
31450 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
31460 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
31470 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c  ommended..*/.SQL
31480 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
31490 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
314a0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
314b0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
314c0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
314d0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
314e0 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
314f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31500 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
31510 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
31520 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
31530 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31540 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
31550 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
31560 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
31570 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
31580 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
31590 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
315a0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
315b0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
315c0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
315d0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
315e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
315f0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
31600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
31610 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
31620 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
31630 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
31640 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
31650 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31660 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
31670 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
31680 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
31690 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
316a0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
316b0 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
316c0 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
316d0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
316e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
316f0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
31700 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
31710 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
31720 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
31730 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
31740 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
31750 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
31760 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
31770 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
31780 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
31790 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
317a0 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
317b0 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
317c0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
317d0 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
317e0 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
317f0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
31800 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
31810 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
31820 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31830 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31840 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
31850 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
31860 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61  DCALL sqlite3_da
31870 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
31880 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
318a0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
318b0 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
318c0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
318d0 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
318e0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
318f0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
31900 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
31910 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
31920 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
31930 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
31940 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
31950 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
31960 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
31970 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
31980 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
31990 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
319a0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
319b0 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
319c0 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
319d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
319e0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
319f0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
31a00 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
31a10 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
31a20 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
31a30 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
31a40 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
31a50 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
31a60 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
31a70 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
31a80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
31a90 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
31aa0 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
31ab0 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
31ac0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31ad0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
31ae0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
31af0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
31b00 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
31b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
31b20 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
31b30 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
31b40 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
31b50 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
31b60 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
31b70 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
31b80 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
31b90 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
31ba0 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
31bb0 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
31bc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
31bd0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
31be0 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
31bf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31c00 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
31c10 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
31c20 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
31c30 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
31c40 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
31c50 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
31c60 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
31c70 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
31c80 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
31c90 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
31ca0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31cb0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
31cc0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
31cd0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
31ce0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
31cf0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
31d00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
31d10 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
31d20 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
31d30 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
31d40 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
31d50 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
31d60 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
31d70 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
31d80 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
31d90 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
31da0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
31db0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
31dc0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
31dd0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
31de0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
31df0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
31e00 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
31e10 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
31e20 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
31e30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
31e40 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
31e50 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
31e60 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
31e70 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
31e80 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
31e90 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
31ea0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
31eb0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
31ec0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
31ed0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
31ee0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
31ef0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31f00 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
31f10 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
31f20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
31f30 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
31f40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31f50 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
31f60 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
31f70 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
31f80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31f90 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
31fa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31fb0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
31fc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
31fd0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
31fe0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
31ff0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
32000 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
32010 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
32020 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
32030 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
32040 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
32050 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32060 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
32070 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
32080 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
32090 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
320a0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
320b0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
320c0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
320d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
320e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
320f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
32100 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
32110 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
32120 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
32130 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
32140 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
32150 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
32160 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
32170 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
32180 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
32190 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
321a0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
321b0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
321c0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
321d0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
321e0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
321f0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
32200 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
32210 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
32220 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
32230 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
32240 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
32250 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
32260 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
32270 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
32280 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
32290 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
322a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
322b0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
322c0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
322d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
322e0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
322f0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
32300 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
32310 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
32320 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
32330 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
32340 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
32350 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
32360 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
32370 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
32380 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
32390 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
323a0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
323b0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
323c0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
323d0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
323e0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
323f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
32400 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
32410 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
32420 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
32430 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32440 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
32450 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
32460 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
32470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32480 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
32490 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
324a0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
324b0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
324c0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
324d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
324e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
324f0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
32500 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
32510 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
32520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32530 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
32540 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
32550 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
32560 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
32570 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
32580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32590 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
325a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
325b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
325c0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
325d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
325e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
325f0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
32600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32610 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
32620 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
32630 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
32640 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
32650 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
32660 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
32670 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
32680 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
32690 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
326a0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
326b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
326c0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
326d0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
326e0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
326f0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
32700 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
32710 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
32720 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
32730 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
32740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32750 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
32760 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
32770 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
32780 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32790 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
327a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
327b0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
327c0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
327d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
327e0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
327f0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
32800 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
32810 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
32820 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
32830 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
32840 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
32850 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
32860 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
32870 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
32880 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
32890 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
328a0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
328b0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
328c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
328d0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
328e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
328f0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
32900 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
32910 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
32920 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
32930 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
32940 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
32950 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
32960 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
32970 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
32980 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
32990 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
329a0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
329b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
329c0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
329d0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
329e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
329f0 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
32a00 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
32a10 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
32a20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32a30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
32a40 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
32a50 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
32a60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
32a70 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
32a80 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
32a90 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
32aa0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32ab0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32ac0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
32ad0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32ae0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
32af0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
32b00 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
32b10 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
32b20 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
32b30 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
32b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32b50 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
32b60 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32b70 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
32b80 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
32b90 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  afe..**.** These
32ba0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
32bb0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
32bc0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
32bd0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
32be0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
32bf0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
32c00 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
32c10 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
32c20 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
32c30 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
32c40 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
32c50 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
32c60 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
32c70 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
32c80 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
32c90 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
32ca0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
32cb0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
32cc0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
32cd0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
32ce0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
32cf0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
32d00 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
32d10 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
32d20 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
32d30 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
32d40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
32d50 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
32d60 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
32d70 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
32d80 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
32d90 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
32da0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
32db0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
32dc0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
32dd0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
32de0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32df0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
32e00 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
32e10 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
32e20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32e30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
32e40 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
32e50 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
32e60 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
32e70 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
32e80 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
32e90 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
32ea0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
32eb0 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
32ec0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
32ed0 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
32ee0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
32ef0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
32f00 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
32f10 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
32f20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
32f30 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
32f40 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
32f50 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
32f60 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
32f70 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
32f80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
32f90 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
32fa0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
32fb0 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
32fc0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
32fd0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
32fe0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
32ff0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
33000 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
33010 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
33020 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
33030 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
33040 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
33050 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
33060 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
33070 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
33080 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
33090 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
330a0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
330b0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
330c0 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
330d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
330e0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
330f0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
33100 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
33110 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
33120 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
33130 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  uote>)^.**.** No
33140 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
33150 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
33160 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
33170 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
33180 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
33190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
331a0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
331b0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
331c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
331d0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
331e0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
331f0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
33200 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
33210 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
33220 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
33230 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
33240 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
33250 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
33260 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
33270 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
33280 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
33290 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
332a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
332b0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
332c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
332d0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
332e0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
332f0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
33300 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
33310 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
33320 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
33330 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
33340 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
33350 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
33360 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
33370 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
33380 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
33390 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
333a0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
333b0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
333c0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
333d0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
333e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
333f0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
33400 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33410 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
33420 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
33430 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
33440 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
33450 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
33460 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
33470 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
33480 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
33490 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
334a0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
334b0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
334c0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
334d0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
334e0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
334f0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
33500 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
33510 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
33520 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
33530 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
33540 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
33550 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
33560 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
33570 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
33580 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
33590 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
335a0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
335b0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
335c0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
335d0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
335e0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f  ** The safest po
335f0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
33600 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
33610 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
33620 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
33630 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
33640 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
33650 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
33660 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
33670 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
33680 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
33690 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
336a0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
336b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
336c0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
336d0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
336e0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
336f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
33700 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
33710 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
33720 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
33730 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
33740 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
33750 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
33760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
33770 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
33780 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
33790 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
337a0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
337b0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
337c0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
337d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
337e0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
337f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33800 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
33810 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
33820 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
33830 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
33840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33850 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
33860 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
33870 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
33880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
33890 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
338a0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
338b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
338c0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
338d0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
338e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
338f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
33900 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
33910 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
33920 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
33930 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
33940 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
33950 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
33960 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
33970 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
33980 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
33990 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
339a0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
339b0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
339c0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
339d0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
339e0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
339f0 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e   Do <em>not</em>
33a00 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
33a10 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
33a20 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
33a30 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
33a40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33a50 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
33a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
33a70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
33a80 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
33a90 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
33aa0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
33ab0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
33ac0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
33ad0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
33ae0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
33af0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
33b00 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
33b10 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
33b20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
33b30 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
33b40 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
33b50 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
33b60 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
33b70 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
33b80 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
33b90 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
33ba0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
33bb0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
33bc0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33bd0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
33be0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33bf0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
33c00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
33c10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
33c20 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
33c30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33c40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33c50 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
33c60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33c70 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
33c80 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33c90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
33ca0 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ble SQLITE_STDCA
33cb0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
33cc0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
33cd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
33ce0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33cf0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
33d00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33d10 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
33d20 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
33d30 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
33d40 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
33d50 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
33d60 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
33d70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33d80 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
33d90 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
33da0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
33db0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
33dc0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
33dd0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33de0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
33df0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
33e00 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33e10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
33e20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33e30 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33e40 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
33e50 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
33e60 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
33e70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
33e80 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
33e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51  qlite3_value *SQ
33ea0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
33eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
33ec0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
33ed0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
33ee0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
33ef0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
33f00 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
33f10 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
33f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
33f30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33f40 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
33f50 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
33f60 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
33f70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
33f80 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
33f90 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
33fa0 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
33fb0 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
33fc0 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
33fd0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
33fe0 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
33ff0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
34000 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34010 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
34020 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
34030 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
34040 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
34050 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
34060 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
34070 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
34080 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
34090 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
340a0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
340b0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
340c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
340d0 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
340e0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
340f0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
34100 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
34110 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
34120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
34130 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
34140 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
34150 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
34160 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
34170 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
34180 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
34190 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
341a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
341b0 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
341c0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
341d0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
341e0 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
341f0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
34200 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
34210 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
34220 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
34230 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
34240 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
34250 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
34260 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
34270 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34280 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
34290 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
342a0 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
342b0 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
342c0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
342d0 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
342e0 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
342f0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
34300 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
34310 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
34320 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
34330 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
34340 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
34350 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
34360 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
34370 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
34380 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
34390 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
343a0 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
343b0 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
343c0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
343d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 69 6e  CALL sqlite3_fin
343e0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
343f0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
34400 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
34410 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
34420 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
34430 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34440 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
34450 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
34460 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
34470 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
34480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34490 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
344a0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
344b0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
344c0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
344d0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
344e0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
344f0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
34500 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
34510 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
34520 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
34530 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
34540 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
34550 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
34560 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
34570 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
34580 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
34590 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
345a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
345b0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
345c0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
345d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
345e0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
345f0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
34600 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
34610 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34620 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
34630 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
34640 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
34650 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
34660 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
34670 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
34680 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
34690 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
346a0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
346b0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
346c0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
346d0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
346e0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
346f0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
34700 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
34710 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34720 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
34730 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
34740 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
34750 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
34760 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
34770 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
34780 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
34790 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
347a0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
347b0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
347c0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
347d0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
347e0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
347f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
34800 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
34810 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34820 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54  ent] S..*/.SQLIT
34830 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
34840 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34850 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
34860 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
34870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
34880 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
34890 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
348a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
348b0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
348c0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
348d0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
348e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
348f0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
34900 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
34910 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
34920 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
34930 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
34940 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
34950 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
34960 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
34970 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
34980 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
34990 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
349a0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
349b0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
349c0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
349d0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
349e0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
349f0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
34a00 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
34a10 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
34a20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
34a30 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
34a40 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
34a50 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
34a60 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
34a70 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
34a80 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
34a90 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
34aa0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
34ab0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
34ac0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
34ad0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
34ae0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
34af0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
34b00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
34b10 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34b20 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
34b30 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
34b40 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
34b50 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
34b60 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
34b70 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
34b80 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
34b90 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
34ba0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
34bb0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
34bc0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
34bd0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
34be0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
34bf0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
34c00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
34c10 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
34c20 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34c30 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
34c40 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
34c50 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
34c60 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
34c70 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
34c80 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
34c90 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
34ca0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
34cb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
34cc0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
34cd0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
34ce0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
34cf0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
34d00 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
34d10 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
34d20 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
34d30 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
34d40 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
34d50 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
34d60 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
34d70 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
34d80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
34d90 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
34da0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
34db0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
34dc0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
34dd0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
34de0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
34df0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
34e00 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
34e10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34e20 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
34e30 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
34e40 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
34e50 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
34e60 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
34e70 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
34e80 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
34e90 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
34ea0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
34eb0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
34ec0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
34ed0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
34ee0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
34ef0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
34f00 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
34f10 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
34f20 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
34f30 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
34f40 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
34f50 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
34f60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
34f70 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
34f80 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
34f90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
34fa0 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
34fb0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
34fc0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
34fd0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
34fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
34ff0 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
35000 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
35010 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
35020 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
35030 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
35040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
35050 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
35060 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
35070 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
35080 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
35090 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
350a0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
350b0 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
350c0 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
350d0 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
350e0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
350f0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
35100 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
35110 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
35120 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
35130 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
35140 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
35150 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
35160 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
35170 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
35180 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
35190 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
351a0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
351b0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
351c0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
351d0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
351e0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
351f0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
35200 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
35210 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
35220 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
35230 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
35240 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
35250 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
35260 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
35270 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
35280 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
35290 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
352a0 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
352b0 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
352c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
352d0 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
352e0 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
352f0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
35300 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
35310 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
35320 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
35330 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
35340 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
35350 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
35360 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
35370 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
35380 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
35390 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
353a0 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
353b0 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
353c0 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
353d0 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
353e0 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
353f0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
35400 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
35410 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
35420 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
35430 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
35440 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
35450 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
35460 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
35470 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
35480 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
35490 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
354a0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
354b0 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
354c0 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
354d0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
354e0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
354f0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
35500 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
35510 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
35520 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
35530 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
35540 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
35550 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
35560 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
35570 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
35580 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
35590 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
355a0 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
355b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
355c0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
355d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
355e0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
355f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
35600 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
35610 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
35620 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
35630 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
35640 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
35650 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
35660 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
35670 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
35680 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
35690 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
356a0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
356b0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
356c0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
356d0 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
356e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
356f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
35700 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
35710 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
35720 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
35730 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
35740 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
35750 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
35760 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
35770 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
35780 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
35790 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
357a0 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
357b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
357c0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
357d0 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
357e0 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
357f0 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
35800 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35810 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35820 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
35830 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35840 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
35850 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
35860 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
35870 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
35880 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
35890 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
358a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
358b0 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
358c0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
358d0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
358e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
358f0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
35900 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
35910 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
35920 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
35930 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
35940 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
35950 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
35960 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
35970 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
35980 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
35990 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
359a0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
359b0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
359c0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
359d0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
359e0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
359f0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
35a00 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
35a10 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
35a20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
35a30 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
35a40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
35a50 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
35a60 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
35a70 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
35a80 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
35a90 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
35aa0 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
35ab0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
35ac0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
35ad0 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
35ae0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
35af0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
35b00 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
35b10 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
35b20 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
35b30 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
35b40 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
35b50 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
35b60 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
35b70 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
35b80 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
35b90 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
35ba0 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
35bb0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
35bc0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
35bd0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
35be0 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
35bf0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
35c00 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
35c10 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
35c20 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
35c30 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
35c40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35c50 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
35c60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35c70 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
35c80 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
35c90 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
35ca0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
35cb0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
35cc0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
35cd0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
35ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
35cf0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
35d00 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
35d10 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
35d20 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
35d30 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
35d40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35d50 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
35d60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35d70 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
35d80 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
35d90 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
35da0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
35db0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
35dc0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
35dd0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
35de0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
35df0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
35e00 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
35e10 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
35e20 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35e30 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
35e40 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
35e50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
35e60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
35e70 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
35e80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35e90 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
35ea0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
35eb0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
35ec0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
35ed0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
35ee0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
35ef0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
35f00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35f10 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
35f20 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
35f30 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
35f40 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35f50 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35f60 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
35f70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35f80 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
35f90 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
35fa0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  LL sqlite3_creat
35fb0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
35fc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
35fd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
35fe0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
35ff0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
36000 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
36010 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
36020 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
36030 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
36040 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
36050 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
36060 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
36070 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
36080 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
36090 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
360a0 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
360b0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
360c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
360d0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
360e0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
360f0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
36100 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
36110 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
36120 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
36130 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
36140 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
36150 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36160 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
36170 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33  1    /* IMP: R-3
36180 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64  7514-35566 */.#d
36190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
361a0 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20  16LE        2   
361b0 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31   /* IMP: R-03371
361c0 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e  -37637 */.#defin
361d0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
361e0 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20          3    /* 
361f0 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31  IMP: R-51971-341
36200 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  54 */.#define SQ
36210 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
36220 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
36230 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36240 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
36250 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
36260 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
36270 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
36280 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
36290 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
362a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
362b0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
362c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
362d0 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
362e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
362f0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
36300 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
36310 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
36320 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
36330 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
36340 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
36350 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
36360 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
36370 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
36380 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36390 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
363a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
363b0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
363c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
363d0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
363e0 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
363f0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
36400 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
36410 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
36420 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
36430 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
36440 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
36450 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
36460 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
36470 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
36480 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
36490 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
364a0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
364b0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
364c0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
364d0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
364e0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
364f0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65  functions.  To e
36500 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d  ncourage program
36510 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  mers to avoid.**
36520 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
36530 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78  , we will not ex
36540 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20  plain what they 
36550 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
36560 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
36570 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49  CATED.SQLITE_API
36580 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
36590 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  ED int SQLITE_ST
365a0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67  DCALL sqlite3_ag
365b0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
365c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
365d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
365e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
365f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
36600 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
36610 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
36620 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
36630 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
36640 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
36650 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
36660 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
36670 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
36680 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
36690 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
366a0 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
366b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
366c0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
366d0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
366e0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
366f0 41 54 45 44 20 76 6f 69 64 20 53 51 4c 49 54 45  ATED void SQLITE
36700 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
36710 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
36720 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
36730 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
36740 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
36750 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
36760 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
36770 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
36780 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
36790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
367a0 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
367b0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
367c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
367d0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
367e0 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
367f0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
36800 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
36810 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
36820 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
36830 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
36840 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
36850 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
36860 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
36870 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
36880 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
36890 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
368a0 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a  aggregate.  .**.
368b0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
368c0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
368d0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
368e0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
368f0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
36900 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36910 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
36920 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36930 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
36940 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
36950 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
36960 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
36970 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
36980 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
36990 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
369a0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
369b0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
369c0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
369d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
369e0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
369f0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
36a00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36a10 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
36a20 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
36a30 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
36a40 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
36a50 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
36a60 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
36a70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
36a80 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
36a90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
36aa0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
36ab0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36ac0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
36ad0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
36ae0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
36af0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
36b00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36b10 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
36b20 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
36b30 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
36b40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
36b50 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
36b60 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
36b70 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
36b80 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
36b90 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
36ba0 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  t these routines
36bb0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
36bc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36bd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
36be0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
36bf0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
36c00 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
36c10 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
36c20 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
36c30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36c40 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
36c50 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
36c60 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
36c70 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
36c80 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
36c90 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
36ca0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
36cb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36cc0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
36cd0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
36ce0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
36cf0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
36d00 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
36d10 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
36d20 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
36d30 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
36d40 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
36d50 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
36d60 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
36d70 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
36d80 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
36d90 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
36da0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
36db0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
36dc0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
36dd0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
36de0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
36df0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
36e00 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
36e10 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
36e20 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
36e30 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
36e40 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
36e50 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
36e60 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
36e70 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
36e80 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
36e90 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
36ea0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
36eb0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
36ec0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
36ed0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
36ee0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
36ef0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
36f00 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
36f10 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
36f20 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
36f30 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
36f40 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
36f50 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
36f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
36f70 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
36f80 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
36f90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
36fa0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
36fb0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
36fc0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
36fd0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
36fe0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
36ff0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
37000 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
37010 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
37020 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
37030 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37040 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
37050 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
37060 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
37070 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
37080 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
37090 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
370a0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
370b0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
370c0 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eters..*/.SQLITE
370d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
370e0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
370f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
37100 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
37110 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
37120 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
37130 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
37140 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
37150 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37160 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
37170 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
37180 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
37190 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
371a0 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51  TE_API double SQ
371b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
371c0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
371d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
371e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
371f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
37200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
37210 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
37220 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
37230 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
37240 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
37250 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
37260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37270 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
37280 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
37290 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
372a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
372b0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
372c0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
372d0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
372e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
372f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
37300 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37310 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
37320 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
37330 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
37340 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
37350 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
37360 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
37370 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
37380 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
37390 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
373a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
373b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
373c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
373d0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
373e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
373f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
37400 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
37410 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
37420 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
37430 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
37440 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67  API3REF: Finding
37450 20 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20   The Subtype Of 
37460 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
37470 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
37480 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  lue.**.** The sq
37490 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74  lite3_value_subt
374a0 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20  ype(V) function 
374b0 72 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74  returns the subt
374c0 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61  ype for.** an [a
374d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
374e0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
374f0 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68   argument V.  Th
37500 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66  e subtype.** inf
37510 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20  ormation can be 
37520 75 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c  used to pass a l
37530 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66  imited amount of
37540 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a   context from.**
37550 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   one SQL functio
37560 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55  n to another.  U
37570 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
37580 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29  result_subtype()
37590 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  ].** routine to 
375a0 73 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20  set the subtype 
375b0 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76  for the return v
375c0 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66  alue of an SQL f
375d0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  unction..**.** S
375e0 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75  QLite makes no u
375f0 73 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74  se of subtype it
37600 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79  self.  It merely
37610 20 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74   passes the subt
37620 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ype.** from the 
37630 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61  result of one [a
37640 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37650 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
37660 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70   into the.** inp
37670 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a  ut of another..*
37680 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 75 6e 73  /.SQLITE_API uns
37690 69 67 6e 65 64 20 69 6e 74 20 53 51 4c 49 54 45  igned int SQLITE
376a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
376b0 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73  _value_subtype(s
376c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
376d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
376e0 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53   Copy And Free S
376f0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
37700 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
37710 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ue.**.** ^The sq
37720 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
37730 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  V) interface mak
37740 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
37750 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
37760 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64  .** object D and
37770 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
37780 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e  er to that copy.
37790 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
377a0 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a  value] returned.
377b0 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74  ** is a [protect
377c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
377d0 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66  ] object even if
377e0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f   the input is no
377f0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
37800 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
37810 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37820 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e  s NULL if V is N
37830 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d  ULL or if a.** m
37840 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37850 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54   fails..**.** ^T
37860 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
37870 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61  _free(V) interfa
37880 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c  ce frees an [sql
37890 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
378a0 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ct.** previously
378b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
378c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
378d0 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20  p()].  ^If V is 
378e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
378f0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76  * then sqlite3_v
37900 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20  alue_free(V) is 
37910 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
37920 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
37930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53  sqlite3_value *S
37940 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
37950 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
37960 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
37970 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37980 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
37990 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
379a0 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
379b0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
379c0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
379d0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
379e0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
379f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
37a00 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
37a10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
37a20 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
37a30 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
37a40 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
37a50 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
37a60 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
37a70 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
37a80 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
37a90 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
37aa0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37ab0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
37ac0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
37ad0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
37ae0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
37af0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
37b00 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
37b10 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
37b20 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
37b30 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
37b40 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
37b50 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
37b60 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37b70 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
37b80 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
37b90 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
37ba0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
37bb0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
37bc0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
37bd0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
37be0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37bf0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
37c00 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
37c10 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
37c20 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
37c30 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
37c40 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
37c50 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
37c60 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
37c70 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
37c80 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
37c90 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
37ca0 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
37cb0 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
37cc0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
37cd0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
37ce0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
37cf0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
37d00 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
37d10 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
37d20 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
37d30 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
37d40 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
37d50 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
37d60 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
37d70 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
37d80 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
37d90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37da0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37db0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
37dc0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
37dd0 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
37de0 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
37df0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
37e00 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
37e10 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
37e20 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
37e30 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
37e40 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
37e50 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
37e60 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
37e70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
37e80 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
37e90 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
37ea0 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
37eb0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
37ec0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
37ed0 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
37ee0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
37ef0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
37f00 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
37f10 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
37f20 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
37f30 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
37f40 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
37f50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
37f60 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
37f70 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
37f80 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
37f90 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
37fa0 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
37fb0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37fc0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
37fd0 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
37fe0 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
37ff0 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
38000 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
38010 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
38020 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
38030 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
38040 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
38050 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
38060 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
38070 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
38080 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
38090 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
380a0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
380b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
380c0 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
380d0 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
380e0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
380f0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
38100 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
38110 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
38120 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
38130 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
38140 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
38150 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
38160 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
38170 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
38180 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
38190 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
381a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
381b0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
381c0 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
381d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
381e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
381f0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
38200 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
38210 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
38220 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
38230 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
38240 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
38250 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
38260 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
38270 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
38280 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
38290 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
382a0 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
382b0 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
382c0 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
382d0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
382e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
382f0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
38300 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
38310 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
38320 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
38330 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
38340 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
38350 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
38360 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
38370 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
38380 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
38390 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
383a0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
383b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
383c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
383d0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
383e0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
383f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
38400 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
38410 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38420 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38430 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
38440 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
38450 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
38460 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
38470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38480 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
38490 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
384a0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
384b0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
384c0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
384d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
384e0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
384f0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
38500 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
38510 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
38520 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
38530 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
38540 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
38550 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
38560 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
38570 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
38580 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  nction..*/.SQLIT
38590 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 53  E_API sqlite3 *S
385a0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
385b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
385c0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
385d0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
385e0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
385f0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
38600 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
38610 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
38620 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
38630 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
38640 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
38650 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
38660 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
38670 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
38680 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
38690 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
386a0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
386b0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
386c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
386d0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
386e0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
386f0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
38700 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
38710 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
38720 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
38730 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
38740 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
38750 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
38760 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
38770 6e 20 61 2