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

Artifact 7e99920e98319e8360cc260eef3da768799a18f4aecf6e0ef9a37a58fcc8f5b4:


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 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71  lite3_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 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71  qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38  .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20  ].** and later) 
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f40: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
64f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6500: 5f 46 49 4c 45 50 52 4f 54 45 43 54 49 4f 4e 5f  _FILEPROTECTION_
6510: 4d 41 53 4b 20 20 20 20 20 20 20 20 20 20 20 20  MASK            
6520: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6530: 20 20 20 20 20 30 78 30 30 37 30 30 30 30 30 0a       0x00700000.
6540: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
6550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6560: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6570: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6580: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6590: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
65a0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
65b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
65c0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
65d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
65e0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
65f0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6600: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6610: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6620: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
6630: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
6640: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
6650: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
6660: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6670: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6680: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6690: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
66a0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66c0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
66d0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
66e0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
66f0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6700: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6710: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6720: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6730: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6740: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6750: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6760: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6770: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6780: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6790: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
67a0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
67b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
67c0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
67d0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
67e0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
67f0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6800: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6810: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6820: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6830: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6840: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6850: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6860: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6870: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6880: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6890: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
68a0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
68b0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
68c0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
68d0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
68e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
68f0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6900: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6910: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6920: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
6930: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
6940: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
6950: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
6960: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6970: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6980: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6990: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
69a0: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
69b0: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
69c0: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
69d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
69e0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
69f0: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6a00: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6a20: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
6a30: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
6a40: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
6a50: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
6a60: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
6a70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
6a80: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
6a90: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
6aa0: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
6ab0: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
6ac0: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
6ad0: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
6ae0: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
6af0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
6b00: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
6b10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b20: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
6b30: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
6b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b50: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
6b60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b70: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6b80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6b90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6ba0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
6bb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bc0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
6bd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6be0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
6bf0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
6c00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c10: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
6c20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c30: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
6c40: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
6c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c60: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
6c70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c80: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
6c90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ca0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
6cb0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
6cc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6cd0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
6ce0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6cf0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
6d00: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6d10: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
6d20: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6d30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6d40: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6d50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6d60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d70: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6d80: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
6d90: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
6da0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6db0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6dc0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6de0: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
6df0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6e00: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
6e10: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6e20: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6e30: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6e40: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6e50: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6e60: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6e70: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6e80: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6e90: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6ea0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6eb0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6ec0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6ed0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6ee0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6ef0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6f00: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6f10: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6f30: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6f40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6f50: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6f60: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6f70: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6f80: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6f90: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6fa0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6fb0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6fc0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6fd0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6fe0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6ff0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7000: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
7010: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
7020: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
7030: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
7040: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
7050: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
7060: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7070: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
7080: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
7090: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
70a0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
70b0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
70c0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
70d0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
70e0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
70f0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
7100: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
7110: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
7120: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7130: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
7140: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
7150: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
7160: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
7170: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
7180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
7190: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
71a0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
71b0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
71c0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
71d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
71e0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
71f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7200: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7210: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
7220: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
7230: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7240: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
7250: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
7260: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
7270: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7280: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7290: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
72a0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
72b0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
72c0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
72d0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
72e0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
72f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7300: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7310: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7320: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7330: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7340: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7350: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7360: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7370: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7380: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7390: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
73a0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
73b0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
73c0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
73d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
73e0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
73f0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7400: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7410: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7420: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7430: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7440: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7450: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7460: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7470: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7480: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7490: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
74a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
74b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
74c0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
74d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
74e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
74f0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7500: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7510: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
7520: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7530: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7540: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7550: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7560: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7570: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7580: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7590: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
75a0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
75b0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
75c0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
75d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
75e0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
75f0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7600: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7610: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
7620: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7630: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7640: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7650: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7660: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7670: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7680: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7690: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
76a0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
76b0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
76c0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
76d0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
76e0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
76f0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7700: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7710: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
7720: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7730: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7740: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7750: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7760: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7770: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7780: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7790: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
77a0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
77b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77c0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
77d0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
77e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
77f0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7800: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7810: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
7820: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7830: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7840: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7850: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7860: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7870: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7880: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7890: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
78a0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
78b0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
78c0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
78d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
78e0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
78f0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7900: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7910: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
7920: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7930: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7940: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7950: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7960: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7970: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7980: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7990: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
79a0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
79b0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
79c0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
79d0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
79e0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
79f0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7a00: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7a10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
7a20: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7a30: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7a40: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7a50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7a60: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7a70: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7a80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7a90: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7aa0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7ab0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7ac0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7ad0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7ae0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7af0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7b00: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7b10: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
7b20: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7b30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7b40: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7b50: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7b60: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7b70: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7b80: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7b90: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7ba0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7bb0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7bc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7bd0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
7be0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
7bf0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
7c00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7c10: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
7c20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7c30: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
7c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7c50: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
7c60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7c70: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7c90: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7ca0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7cb0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7cc0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
7cd0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
7ce0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
7cf0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
7d00: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
7d10: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
7d20: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7d30: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7d40: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7d50: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7d60: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7d70: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7d80: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7d90: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7da0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7db0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7dc0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7dd0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7de0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7df0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7e00: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7e10: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7e20: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7e30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7e40: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7e50: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7e60: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7e70: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7e80: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7e90: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7ea0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7eb0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7ec0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7ed0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7ee0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7ef0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7f00: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7f10: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7f20: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7f30: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7f40: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7f50: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7f60: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7f70: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7f80: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7f90: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7fa0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7fb0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7fc0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7fd0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7fe0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7ff0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
8000: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
8010: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
8020: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
8030: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
8040: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
8050: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
8060: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
8070: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
8080: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
8090: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
80a0: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
80b0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
80c0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
80d0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
80e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
80f0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
8100: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8110: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
8120: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
8130: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
8140: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
8150: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8160: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
8170: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
8180: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
8190: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
81a0: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
81b0: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
81c0: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
81d0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
81e0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
81f0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
8200: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
8210: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
8220: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
8230: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
8240: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
8250: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
8260: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
8270: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
8280: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
8290: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
82a0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
82b0: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
82c0: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
82d0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
82e0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
82f0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
8300: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8310: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8320: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8330: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8340: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8350: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8360: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8370: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8380: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8390: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
83a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
83c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
83e0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
83f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8400: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
8410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8420: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8430: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8440: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8450: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8460: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c  EQUENTIAL].** <l
8470: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8480: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
8490: 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20  N_OPEN].** <li> 
84a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
84b0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
84c0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
84d0: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
84e0: 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  LE].** </ul>.**.
84f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
8510: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8520: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8530: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8540: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8550: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8560: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8570: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8580: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8590: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
85a0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
85b0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
85c0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
85d0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
85e0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
85f0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8600: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
8610: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8620: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8630: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8640: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8650: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8660: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8670: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8680: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8690: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
86a0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
86b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
86c0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
86d0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
86e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
86f0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
8700: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
8710: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8720: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8730: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8740: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8750: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8760: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8770: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8780: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8790: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
87a0: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
87b0: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
87c0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
87d0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
87e0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
87f0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8800: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8810: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8820: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8830: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8840: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8850: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8860: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8870: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8880: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8890: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
88a0: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
88b0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
88c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
88d0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
88e0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
88f0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8900: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8910: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8920: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8930: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8940: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8950: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8960: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8970: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8980: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8990: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
89a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
89b0: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
89c0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
89d0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
89e0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
89f0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8a00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8a10: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8a20: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8a30: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8a40: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8a50: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8a60: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8a70: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8a80: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8a90: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8aa0: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8ab0: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8ac0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8ad0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8ae0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8af0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8b00: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8b10: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8b20: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8b30: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8b40: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8b50: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8b60: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8b70: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8b80: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8b90: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8ba0: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8bb0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8bc0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8bd0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8be0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8bf0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8c00: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8c10: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8c20: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8c30: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8c40: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8c50: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8c60: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8c70: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8c80: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8c90: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8ca0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8cb0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8cc0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8cd0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8ce0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8cf0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8d00: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8d10: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8d20: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8d30: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8d40: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8d50: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8d60: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
8d70: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
8d80: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
8d90: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8da0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
8db0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8dc0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8dd0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8de0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8df0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8e00: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8e10: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8e20: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8e30: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8e40: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8e50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e60: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
8e70: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e80: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8e90: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8ea0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8eb0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8ec0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8ed0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8ee0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8ef0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8f00: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8f10: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8f20: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8f30: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8f40: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8f50: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8f60: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8f70: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8f80: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8f90: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8fa0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8fb0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8fc0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8fd0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8fe0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
8ff0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
9000: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
9010: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9020: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
9030: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9040: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9050: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
9060: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9070: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
9080: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
9090: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
90a0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
90b0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
90c0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
90d0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
90e0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
90f0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
9100: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
9110: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9120: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9130: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9140: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9150: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9160: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9170: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
9180: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
9190: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
91a0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
91b0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
91c0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
91d0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
91e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
91f0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
9200: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9210: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9220: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9230: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9240: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9250: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9260: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9270: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9280: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9290: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
92a0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
92b0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
92c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
92d0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
92e0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
92f0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
9300: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
9310: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9320: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9330: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9340: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9350: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9360: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9370: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9380: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9390: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
93a0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
93b0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
93c0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
93d0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
93e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
93f0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
9400: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9410: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9420: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9430: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9440: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9460: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9470: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9480: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9490: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
94a0: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
94b0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
94c0: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
94d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
94e0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
94f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9500: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9510: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9520: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9530: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9540: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9550: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9560: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9570: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
9580: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
9590: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
95a0: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
95b0: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
95c0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
95d0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
95e0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
95f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9600: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
9610: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9620: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9630: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9640: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9660: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9670: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9680: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9690: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
96a0: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
96b0: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
96c0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
96d0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
96e0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
96f0: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
9700: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
9710: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9720: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9730: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9740: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9750: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9760: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9770: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9780: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9790: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
97a0: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
97b0: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
97c0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
97d0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
97e0: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
97f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9800: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9810: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9820: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9830: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9840: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9850: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9860: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9870: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
9880: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
9890: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
98a0: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
98b0: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
98c0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
98d0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
98e0: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
98f0: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9900: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9910: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9920: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9930: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9940: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9950: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9960: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9970: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
9980: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9990: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
99a0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
99b0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
99c0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
99d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
99e0: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
99f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9a00: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9a10: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9a20: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9a30: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9a40: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9a50: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9a60: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9a70: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
9a80: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
9a90: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
9aa0: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
9ab0: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
9ac0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9ad0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9ae0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9af0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9b00: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9b10: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9b20: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9b30: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9b40: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9b50: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9b60: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9b70: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9b80: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9b90: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9ba0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9bb0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9bc0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9bd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9be0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9bf0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9c00: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9c10: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9c20: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9c30: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9c40: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9c50: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9c60: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9c70: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9c80: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9c90: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9ca0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9cb0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9cc0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9cd0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9ce0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9cf0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9d00: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9d10: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
9d20: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
9d30: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
9d40: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
9d50: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
9d60: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
9d70: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
9d80: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
9d90: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
9da0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
9db0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
9dc0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
9dd0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9de0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9df0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9e00: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9e10: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9e20: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9e30: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9e40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
9e50: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
9e60: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9e70: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9e80: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9e90: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9ea0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9eb0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9ec0: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9ed0: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9ee0: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9ef0: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9f00: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9f10: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9f20: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9f30: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9f40: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
9f50: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
9f60: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9f70: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9f80: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9f90: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9fa0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9fb0: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9fc0: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9fd0: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9fe0: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9ff0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a000: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
a010: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
a020: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
a030: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
a040: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
a050: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
a060: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
a070: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
a080: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
a090: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
a0a0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
a0b0: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
a0c0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
a0d0: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
a0e0: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
a0f0: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
a100: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
a110: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
a120: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
a130: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
a140: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
a150: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
a160: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
a170: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
a180: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
a190: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
a1a0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
a1b0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
a1c0: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
a1d0: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
a1e0: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
a1f0: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
a200: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a210: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
a220: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
a230: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
a240: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
a250: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
a260: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
a270: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
a280: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
a290: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
a2a0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a2b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a2c0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a2d0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a2e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a2f0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a300: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a310: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
a320: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
a330: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
a340: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
a350: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a360: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a370: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a380: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a390: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
a3a0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
a3b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a3c0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a3d0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
a3e0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a3f0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a400: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a410: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a420: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a430: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
a440: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
a450: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
a460: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
a470: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
a480: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
a490: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
a4a0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
a4b0: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
a4c0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
a4d0: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
a4e0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a4f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a500: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a510: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a520: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a530: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a540: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a550: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
a560: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a570: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
a580: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
a590: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a5a0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a5b0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a5c0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a5d0: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
a5e0: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
a5f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a600: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a610: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a620: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a630: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a640: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a650: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
a660: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
a670: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
a680: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
a690: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
a6a0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
a6b0: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
a6c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a6d0: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
a6e0: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
a6f0: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
a700: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
a710: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
a720: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
a730: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a740: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
a750: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a760: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
a770: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
a780: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
a790: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
a7a0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
a7b0: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
a7c0: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
a7d0: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
a7e0: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
a7f0: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
a800: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
a810: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
a820: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
a830: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
a840: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
a850: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
a860: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
a870: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
a880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a890: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
a8a0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
a8b0: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
a8c0: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
a8d0: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
a8e0: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
a8f0: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
a900: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
a910: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
a920: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
a930: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
a940: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
a950: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
a960: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
a970: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
a980: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
a990: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
a9a0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
a9b0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
a9c0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
a9d0: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
a9e0: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
a9f0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
aa00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
aa10: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54  _POINTER]].** ^T
aa20: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aa30: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  _VFS_POINTER] op
aa40: 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69  code finds a poi
aa50: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d  nter to the top-
aa60: 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d  level.** [VFSes]
aa70: 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73   currently in us
aa80: 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65  e.  ^(The argume
aa90: 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74  nt X in.** sqlit
aaa0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
aab0: 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  db,SQLITE_FCNTL_
aac0: 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d  VFS_POINTER,X) m
aad0: 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70  ust be.** of typ
aae0: 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  e "[sqlite3_vfs]
aaf0: 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f   **".  This opco
ab00: 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a  des will set *X.
ab10: 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20  ** to a pointer 
ab20: 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c  to the top-level
ab30: 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e   VFS.)^.** ^When
ab40: 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69   there are multi
ab50: 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e  ple VFS shims in
ab60: 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73   the stack, this
ab70: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68   opcode finds th
ab80: 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20  e.** upper-most 
ab90: 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  shim only..**.**
aba0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
abb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20  NTL_PRAGMA]].** 
abc0: 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41  ^Whenever a [PRA
abd0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  GMA] statement i
abe0: 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51  s parsed, an [SQ
abf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ac00: 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  A] .** file cont
ac10: 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74  rol is sent to t
ac20: 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  he open [sqlite3
ac30: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f  _file] object co
ac40: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74  rresponding.** t
ac50: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
ac60: 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65  ile to which the
ac70: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
ac80: 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61  t refers. ^The a
ac90: 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
aca0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
acb0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
acc0: 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79  trol is an array
acd0: 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20   of.** pointers 
ace0: 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72  to strings (char
acf0: 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65  **) in which the
ad00: 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20   second element 
ad10: 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20  of the array.** 
ad20: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
ad30: 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68  he pragma and th
ad40: 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20  e third element 
ad50: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
ad60: 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61  to the.** pragma
ad70: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
ad80: 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72  pragma has no ar
ad90: 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61  gument.  ^The ha
ada0: 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20  ndler for an.** 
adb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
adc0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
add0: 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  ol can optionall
ade0: 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74  y make the first
adf0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74   element.** of t
ae00: 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65  he char** argume
ae10: 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  nt point to a st
ae20: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
ae30: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
ae40: 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65  ntf()].** or the
ae50: 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20   equivalent and 
ae60: 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c  that string will
ae70: 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75   become the resu
ae80: 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  lt of the pragma
ae90: 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72   or.** the error
aea0: 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20   message if the 
aeb0: 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49  pragma fails. ^I
aec0: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
aed0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
aee0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
aef0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  rns [SQLITE_NOTF
af00: 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d  OUND], then norm
af10: 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20  al .** [PRAGMA] 
af20: 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69  processing conti
af30: 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b  nues.  ^If the [
af40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
af50: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
af60: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
af70: 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74  LITE_OK], then t
af80: 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65  he parser assume
af90: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46  s that the.** VF
afa0: 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68  S has handled th
afb0: 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20  e PRAGMA itself 
afc0: 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67  and the parser g
afd0: 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70  enerates a no-op
afe0: 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
aff0: 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74  tement if result
b000: 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c   string is NULL,
b010: 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73   or that returns
b020: 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
b030: 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  e result string 
b040: 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  if the string is
b050: 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49   non-NULL..** ^I
b060: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
b070: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
b080: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
b090: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
b0a0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
b0b0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
b0c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
b0d0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
b0e0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
b0f0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
b100: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
b110: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
b120: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
b130: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
b140: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
b150: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
b160: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b170: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
b180: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
b190: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
b1a0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
b1b0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
b1c0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
b1d0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
b1e0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
b1f0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
b200: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b210: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
b220: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
b230: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
b240: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b250: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
b260: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
b270: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
b280: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
b290: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
b2a0: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
b2b0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
b2c0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
b2d0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
b2e0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
b2f0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
b300: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
b310: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
b320: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
b330: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
b340: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
b350: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
b360: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
b370: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
b380: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
b390: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
b3a0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
b3b0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
b3c0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
b3d0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
b3e0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
b3f0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
b400: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
b410: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
b420: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
b430: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
b440: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
b450: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
b460: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
b470: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
b480: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
b490: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
b4a0: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
b4b0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
b4c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b4d0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
b4e0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
b4f0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
b500: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b510: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
b520: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
b530: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
b540: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
b550: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
b560: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
b570: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
b580: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
b590: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
b5a0: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
b5b0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
b5c0: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
b5d0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
b5e0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
b5f0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
b600: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
b610: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
b620: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
b630: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
b640: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
b650: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
b660: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
b670: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
b680: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
b690: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
b6a0: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
b6b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
b6c0: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
b6d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b6e0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
b6f0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b700: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
b710: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
b720: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
b730: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b740: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b750: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b760: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b770: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b780: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b790: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b7a0: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b7b0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b7c0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b7d0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b7e0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b7f0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b800: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b810: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b820: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b830: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b840: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b850: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b860: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b870: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b880: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b890: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b8a0: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b8b0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b8c0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b8d0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b8e0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b8f0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b900: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b910: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b920: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b930: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b940: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b950: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b960: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b970: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b980: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b990: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b9a0: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b9b0: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b9c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b9d0: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b9e0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b9f0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
ba00: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
ba10: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
ba20: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
ba30: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
ba40: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
ba50: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
ba60: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
ba70: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
ba80: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
ba90: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
baa0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
bab0: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
bac0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bad0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
bae0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
baf0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
bb00: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
bb10: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
bb20: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
bb30: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
bb40: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
bb50: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
bb60: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
bb70: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
bb80: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
bb90: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
bba0: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
bbb0: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
bbc0: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
bbd0: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
bbe0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bbf0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
bc00: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bc10: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
bc20: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
bc30: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
bc40: 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e  obtain the.** un
bc50: 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20  derlying native 
bc60: 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f  file handle asso
bc70: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66 69  ciated with a fi
bc80: 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73  le handle.  This
bc90: 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c   file.** control
bca0: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
bcb0: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f  argument as a po
bcc0: 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76  inter to a nativ
bcd0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e  e file handle an
bce0: 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20  d.** writes the 
bcf0: 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20  resulting value 
bd00: 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  there..**.** <li
bd10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd20: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bd30: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bd40: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
bd50: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
bd60: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
bd70: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
bd80: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
bd90: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
bda0: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
bdb0: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
bdc0: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
bdd0: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
bde0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
bdf0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
be00: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
be10: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
be20: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
be30: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
be40: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
be50: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  fined..**.** <li
be60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
be70: 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54  WAL_BLOCK]].** T
be80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
be90: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61  _WAL_BLOCK] is a
bea0: 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56   signal to the V
beb0: 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74  FS layer that it
bec0: 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76   might.** be adv
bed0: 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f  antageous to blo
bee0: 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57  ck on the next W
bef0: 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c  AL lock if the l
bf00: 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64  ock is not immed
bf10: 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61  iately.** availa
bf20: 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75  ble.  The WAL su
bf30: 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74  bsystem issues t
bf40: 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e  his signal durin
bf50: 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d  g rare.** circum
bf60: 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72  stances in order
bf70: 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65   to fix a proble
bf80: 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20  m with priority 
bf90: 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70  inversion..** Ap
bfa0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
bfb0: 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75  d <em>not</em> u
bfc0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
bfd0: 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  trol..**.** <li>
bfe0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  [[SQLITE_FCNTL_Z
bff0: 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b  IPVFS]].** The [
c000: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
c010: 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  VFS] opcode is i
c020: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69  mplemented by zi
c030: 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f  pvfs only. All o
c040: 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75  ther.** VFS shou
c050: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
c060: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68  _NOTFOUND for th
c070: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a  is opcode..**.**
c080: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c090: 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65  NTL_RBU]].** The
c0a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
c0b0: 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d  BU] opcode is im
c0c0: 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65  plemented by the
c0d0: 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73 65   special VFS use
c0e0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20  d by.** the RBU 
c0f0: 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20  extension only. 
c100: 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73   All other VFS s
c110: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
c120: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
c130: 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  .** this opcode.
c140: 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23    .** </ul>.*/.#
c150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c160: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
c170: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
c180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c190: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
c1a0: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
c1b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1c0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
c1d0: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
c1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c1f0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c200: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
c210: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c220: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
c230: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
c240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
c250: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
c260: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
c270: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
c280: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
c290: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
c2a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
c2b0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
c2c0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
c2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
c2e0: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
c2f0: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
c310: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
c320: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
c330: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
c340: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
c350: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
c360: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
c390: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
c3a0: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
c3b0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
c3c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
c3d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
c3e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c3f0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
c400: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
c410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c420: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
c430: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
c440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c450: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
c460: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
c470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c480: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
c490: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
c4a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c4b0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
c4c0: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
c4d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c4e0: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
c4f0: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
c500: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c510: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
c520: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
c530: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c540: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
c550: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
c560: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
c570: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
c580: 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20       24.#define 
c590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
c5a0: 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20 20  VFS             
c5b0: 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53      25.#define S
c5c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20  QLITE_FCNTL_RBU 
c5d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c5e0: 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51     26.#define SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
c600: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
c610: 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c    27.#define SQL
c620: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
c630: 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  L_POINTER       
c640: 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   28.#define SQLI
c650: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
c660: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
c670: 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  29.#define SQLIT
c680: 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20  E_FCNTL_PDB     
c690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
c6a0: 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64  0../* deprecated
c6b0: 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e   names */.#defin
c6c0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
c6d0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
c6f0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
c700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
c710: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c720: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c730: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
c740: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c750: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
c760: 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45            SQLITE
c770: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
c780: 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  O.../*.** CAPI3R
c790: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
c7a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
c7b0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
c7c0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
c7d0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
c7e0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
c7f0: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
c800: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
c810: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
c820: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
c830: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
c840: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
c850: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c860: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
c870: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
c880: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
c890: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
c8a0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
c8b0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
c8c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
c8d0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
c8e0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
c8f0: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
c900: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
c910: 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62  CAPI3REF: Loadab
c920: 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75  le Extension Thu
c930: 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  nk.**.** A point
c940: 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65  er to the opaque
c950: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
c960: 74 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20  tines structure 
c970: 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  is passed as.** 
c980: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
c990: 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69  ter to entry poi
c9a0: 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65  nts of [loadable
c9b0: 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54   extensions].  T
c9c0: 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  his.** structure
c9d0: 20 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66   must be typedef
c9e0: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77  ed in order to w
c9f0: 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69  ork around compi
ca00: 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20  ler warnings.** 
ca10: 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d  on some platform
ca20: 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
ca30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69  ruct sqlite3_api
ca40: 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65  _routines sqlite
ca50: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a  3_api_routines;.
ca60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ca70: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
ca80: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
ca90: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
caa0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
cab0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
cac0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
cad0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
cae0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
caf0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
cb00: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
cb10: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
cb20: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
cb30: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
cb40: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
cb50: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
cb60: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
cb70: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
cb80: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
cb90: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
cba0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
cbb0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
cbc0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
cbd0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
cbe0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
cbf0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
cc00: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
cc10: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
cc20: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
cc30: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
cc40: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
cc50: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
cc60: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
cc70: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
cc80: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
cc90: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
cca0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
ccb0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
ccc0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
ccd0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
cce0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
ccf0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
cd00: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
cd10: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
cd20: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
cd30: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
cd40: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
cd50: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
cd60: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
cd70: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
cd80: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
cd90: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
cda0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
cdb0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
cdc0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
cdd0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
cde0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
cdf0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ce00: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ce10: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
ce20: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
ce30: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
ce40: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
ce50: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
ce60: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
ce70: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
ce80: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
ce90: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
cea0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
ceb0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
cec0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
ced0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
cee0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
cef0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
cf00: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
cf10: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
cf20: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
cf30: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
cf40: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
cf50: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
cf60: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
cf70: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
cf80: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
cf90: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
cfa0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
cfb0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
cfc0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
cfd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
cfe0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
cff0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
d000: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
d010: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
d020: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
d030: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
d040: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
d050: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
d060: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
d070: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
d080: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
d090: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
d0a0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
d0b0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
d0c0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
d0d0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
d0e0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
d0f0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
d100: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
d110: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
d120: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
d130: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
d140: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
d150: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
d160: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
d170: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
d180: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
d190: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
d1a0: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
d1b0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
d1c0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
d1d0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
d1e0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
d1f0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
d200: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
d210: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
d220: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
d230: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
d240: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
d250: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
d260: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
d270: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
d280: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
d290: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
d2a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
d2b0: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
d2c0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
d2d0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
d2e0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
d2f0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
d300: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
d310: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
d320: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
d330: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
d340: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
d350: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
d360: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
d370: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
d380: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
d390: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
d3a0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
d3b0: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
d3c0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
d3d0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
d3e0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
d3f0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
d400: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
d410: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
d420: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
d430: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
d440: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
d450: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
d460: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
d470: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
d480: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
d490: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
d4a0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
d4b0: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
d4c0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
d4d0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
d4e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
d4f0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
d500: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
d510: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
d520: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
d530: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
d540: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
d550: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
d560: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
d570: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
d580: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
d590: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
d5a0: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
d5b0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
d5c0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
d5d0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
d5e0: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
d5f0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
d600: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
d610: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d620: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d630: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
d640: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d650: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
d660: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d670: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
d680: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d690: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
d6a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d6b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
d6c0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
d6d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
d6e0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
d6f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d700: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
d710: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d720: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
d730: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
d740: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
d750: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
d760: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
d770: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
d780: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
d790: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
d7a0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
d7b0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
d7c0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
d7d0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
d7e0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
d7f0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
d800: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
d810: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
d820: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
d830: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
d840: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
d850: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
d860: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
d870: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
d880: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
d890: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
d8a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
d8b0: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
d8c0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
d8d0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
d8e0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
d8f0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
d900: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
d910: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
d920: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
d930: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
d940: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
d950: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
d960: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d970: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d980: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
d990: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
d9a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d9b0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
d9c0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
d9d0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
d9e0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
d9f0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
da00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
da10: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
da20: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
da30: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
da40: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
da50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
da60: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
da70: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
da80: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
da90: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
daa0: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
dab0: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
dac0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
dad0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
dae0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
daf0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
db00: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
db10: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
db20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
db30: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
db40: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
db50: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
db60: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
db70: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
db80: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
db90: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
dba0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
dbb0: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
dbc0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
dbd0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
dbe0: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
dbf0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
dc00: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
dc10: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
dc20: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
dc30: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
dc40: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
dc50: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
dc60: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
dc70: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
dc80: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
dc90: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
dca0: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
dcb0: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
dcc0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
dcd0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
dce0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
dcf0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
dd00: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
dd10: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
dd20: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
dd30: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
dd40: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
dd50: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
dd60: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
dd70: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
dd80: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
dd90: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
dda0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
ddb0: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
ddc0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
ddd0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
dde0: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
ddf0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
de00: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
de10: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
de20: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
de30: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
de40: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
de50: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
de60: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
de70: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
de80: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
de90: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
dea0: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
deb0: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
dec0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
ded0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
dee0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
def0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
df00: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
df10: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
df20: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
df30: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
df40: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
df50: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
df60: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
df70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
df80: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
df90: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
dfa0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
dfb0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
dfc0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
dfd0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
dfe0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
dff0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
e000: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
e010: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
e020: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
e030: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
e040: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
e050: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
e060: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
e070: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
e080: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
e090: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
e0a0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
e0b0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
e0c0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
e0d0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
e0e0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
e0f0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
e100: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
e110: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
e120: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
e130: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
e140: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
e150: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
e160: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
e170: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
e180: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
e190: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
e1a0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
e1b0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
e1c0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
e1d0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
e1e0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
e1f0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
e200: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
e210: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
e220: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
e230: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
e240: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
e250: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
e260: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
e270: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
e280: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
e290: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
e2a0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
e2b0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
e2c0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
e2d0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
e2e0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
e2f0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
e300: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
e310: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
e320: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
e330: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
e340: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
e350: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
e360: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
e370: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
e380: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
e390: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
e3a0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
e3b0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
e3c0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
e3d0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
e3e0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
e3f0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
e400: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
e410: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
e420: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
e430: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
e440: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
e450: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
e460: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
e470: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
e480: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
e490: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
e4a0: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
e4b0: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
e4c0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
e4d0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
e4e0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
e4f0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
e500: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
e510: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
e520: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
e530: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
e540: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
e550: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
e560: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
e570: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
e580: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
e590: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
e5a0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
e5b0: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
e5c0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
e5d0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
e5e0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
e5f0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
e600: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
e610: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
e620: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
e630: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
e640: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
e650: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
e660: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
e670: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
e680: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
e690: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
e6a0: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
e6b0: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
e6c0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
e6d0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
e6e0: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
e6f0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
e700: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
e710: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
e720: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
e730: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
e740: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
e750: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
e760: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
e770: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
e780: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
e790: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
e7a0: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
e7b0: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
e7c0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
e7d0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
e7e0: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
e7f0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
e800: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
e810: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
e820: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
e830: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
e840: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
e850: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
e860: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
e870: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
e880: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
e890: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
e8a0: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
e8b0: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
e8c0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
e8d0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
e8e0: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
e8f0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
e900: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
e910: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e920: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
e930: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
e940: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
e950: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
e960: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
e970: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
e980: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
e990: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
e9a0: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
e9b0: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
e9c0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
e9d0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
e9e0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
e9f0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
ea00: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
ea10: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
ea20: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
ea30: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
ea40: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
ea50: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
ea60: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
ea70: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
ea80: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
ea90: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
eaa0: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
eab0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
eac0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
ead0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
eae0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
eaf0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
eb00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
eb10: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
eb20: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
eb30: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
eb40: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
eb50: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
eb60: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
eb70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
eb80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
eb90: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
eba0: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
ebb0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ebc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
ebd0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
ebe0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
ebf0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
ec00: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ec10: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ec20: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
ec30: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
ec40: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
ec50: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ec60: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
ec70: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
ec80: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
ec90: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
eca0: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
ecb0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
ecc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
ecd0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
ece0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
ecf0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
ed00: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
ed10: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
ed20: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
ed30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
ed40: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
ed50: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
ed60: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
ed70: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
ed80: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
ed90: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
eda0: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
edb0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
edc0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
edd0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
ede0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
edf0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
ee00: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
ee10: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
ee20: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
ee30: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
ee40: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
ee50: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
ee60: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
ee70: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
ee80: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
ee90: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
eea0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
eeb0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
eec0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
eed0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
eee0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
eef0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
ef00: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
ef10: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
ef20: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
ef30: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
ef40: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
ef50: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ef60: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
ef70: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
ef80: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
ef90: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
efa0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
efb0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
efc0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
efd0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
efe0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
eff0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
f000: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
f010: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
f020: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
f030: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
f040: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
f050: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
f060: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
f070: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
f080: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
f090: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
f0a0: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
f0b0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
f0c0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
f0d0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
f0e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
f0f0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
f100: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
f110: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
f120: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
f130: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
f140: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
f150: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
f160: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
f170: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
f180: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
f190: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
f1a0: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
f1b0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
f1c0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
f1d0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
f1e0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
f1f0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f200: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
f210: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
f220: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
f230: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
f240: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
f250: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f260: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
f270: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
f280: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
f290: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
f2a0: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
f2b0: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
f2c0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
f2d0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
f2e0: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
f2f0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
f300: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
f310: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
f320: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
f330: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
f340: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
f350: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
f360: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
f370: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
f380: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
f390: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
f3a0: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
f3b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
f3c0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f3d0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
f3e0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
f3f0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
f400: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f410: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
f420: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
f430: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
f440: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
f450: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
f460: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
f470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f480: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
f490: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
f4a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
f4b0: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
f4c0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
f4d0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
f4e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f4f0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
f500: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
f510: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
f520: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
f530: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
f540: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
f550: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
f560: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
f570: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
f580: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
f590: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
f5a0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
f5b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
f5c0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
f5d0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
f5e0: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
f5f0: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
f600: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
f610: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
f620: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
f630: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
f640: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f650: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
f660: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
f670: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f680: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
f690: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
f6a0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f6b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f6c0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
f6d0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
f6e0: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
f6f0: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
f700: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
f710: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
f720: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
f730: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
f740: 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
f750: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
f760: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
f770: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
f780: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
f790: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f7a0: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
f7b0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f7c0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
f7d0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
f7e0: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
f7f0: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
f800: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
f810: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f820: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
f830: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
f840: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
f850: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
f860: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
f870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f880: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
f890: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f8a0: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
f8b0: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
f8c0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f8d0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
f8e0: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
f8f0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
f900: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
f910: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
f920: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
f930: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
f940: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
f950: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
f960: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
f970: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
f980: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
f990: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f9a0: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
f9b0: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
f9c0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
f9d0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
f9e0: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
f9f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fa00: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
fa10: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
fa20: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
fa30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
fa40: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
fa50: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
fa60: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
fa70: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
fa80: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
fa90: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
faa0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
fab0: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
fac0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
fad0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
fae0: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
faf0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
fb00: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
fb10: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
fb20: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
fb30: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
fb40: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
fb50: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
fb60: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
fb70: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
fb80: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
fb90: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
fba0: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
fbb0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
fbc0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fbd0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
fbe0: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
fbf0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
fc00: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
fc10: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
fc20: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fc30: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
fc40: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
fc50: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
fc60: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
fc70: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
fc80: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
fc90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
fca0: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
fcb0: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
fcc0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
fcd0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
fce0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
fcf0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fd00: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
fd10: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
fd20: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
fd30: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fd40: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
fd50: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
fd60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
fd70: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
fd80: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
fd90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fda0: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
fdb0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
fdc0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
fdd0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
fde0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
fdf0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
fe00: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
fe10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fe20: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
fe30: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
fe40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe50: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
fe60: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
fe70: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
fe80: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
fe90: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
fea0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
feb0: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
fec0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
fed0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
fee0: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
fef0: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
ff00: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
ff10: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
ff20: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
ff30: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
ff40: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
ff50: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
ff60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
ff70: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
ff80: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
ff90: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
ffa0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
ffb0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
ffc0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
ffd0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
ffe0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
fff0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
10000 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
10010 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
10020 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
10030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10040 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
10050 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
10060 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
10070 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
10080 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
10090 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
100a0 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
100b0 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
100c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
100d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
100e0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
100f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10100 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
10110 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
10120 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
10130 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
10140 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
10150 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
10160 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
10170 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
10180 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10190 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
101a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
101b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
101c0 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
101d0 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
101e0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
101f0 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
10200 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
10210 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
10220 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
10230 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
10240 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
10250 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
10260 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
10270 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10280 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
10290 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
102a0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
102b0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
102c0 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
102d0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
102e0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
102f0 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
10300 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10310 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
10320 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
10330 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
10340 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
10350 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10360 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
10370 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
10380 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
10390 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
103a0 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
103b0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
103c0 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
103d0 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
103e0 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
103f0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
10400 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
10410 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
10420 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
10430 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
10440 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
10450 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
10460 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10470 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
10480 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
10490 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
104a0 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
104b0 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
104c0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
104d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
104e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
104f0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
10500 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
10510 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
10520 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
10530 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
10540 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
10550 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
10560 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
10570 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
10580 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
10590 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
105a0 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
105b0 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
105c0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
105d0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
105e0 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
105f0 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
10600 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
10610 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
10620 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
10630 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
10640 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
10650 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
10660 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
10670 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
10680 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
10690 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
106a0 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
106b0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
106c0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
106d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
106e0 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
106f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
10700 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
10710 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
10720 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
10730 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
10740 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
10750 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
10760 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
10770 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
10780 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10790 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
107a0 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
107b0 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
107c0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
107d0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
107e0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
107f0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10800 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10810 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
10820 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
10830 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
10840 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
10850 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
10860 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
10870 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
10880 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
10890 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
108a0 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
108b0 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
108c0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
108d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
108e0 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
108f0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
10900 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
10910 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
10920 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10930 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
10940 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
10950 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10960 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10970 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
10980 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
10990 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
109a0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
109b0 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
109c0 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
109d0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
109e0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
109f0 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
10a00 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10a10 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
10a20 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
10a30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
10a40 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
10a50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10a60 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
10a70 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
10a80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
10a90 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10aa0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
10ab0 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
10ac0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
10ad0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
10ae0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
10af0 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
10b00 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
10b10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
10b20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
10b30 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
10b40 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
10b50 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
10b60 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
10b70 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
10b80 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
10b90 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
10ba0 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
10bb0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
10bc0 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
10bd0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
10be0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10bf0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10c00 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
10c10 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
10c20 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
10c30 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
10c40 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
10c50 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
10c60 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
10c70 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
10c80 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
10c90 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
10ca0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10cb0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
10cc0 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
10cd0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
10ce0 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
10cf0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
10d00 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10d10 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
10d20 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
10d30 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
10d40 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
10d50 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
10d60 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
10d70 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
10d80 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
10d90 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
10da0 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
10db0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
10dc0 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
10dd0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
10de0 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
10df0 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
10e00 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
10e10 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
10e20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
10e30 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
10e40 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
10e50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10e60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
10e70 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
10e80 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
10e90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
10ea0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
10eb0 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
10ec0 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
10ed0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
10ee0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
10ef0 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
10f00 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
10f10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f20 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
10f30 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
10f40 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
10f50 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10f60 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
10f70 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
10f80 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
10f90 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
10fa0 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
10fb0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
10fc0 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
10fd0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
10fe0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
10ff0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
11000 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
11010 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
11020 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
11030 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
11040 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
11050 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  nections.** METH
11060 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
11070 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
11080 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
11090 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
110a0 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
110b0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
110c0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
110d0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
110e0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
110f0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
11100 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
11110 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
11120 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
11130 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
11140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
11150 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
11160 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
11170 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
11180 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
11190 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
111a0 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
111b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
111c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
111d0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
111e0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
111f0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
11200 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
11210 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
11220 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11230 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
11240 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
11250 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
11260 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
11270 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
11280 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
11290 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
112a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
112b0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
112c0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
112d0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
112e0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
112f0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
11300 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
11310 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
11320 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
11330 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
11340 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
11350 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
11360 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
11370 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
11380 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
11390 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
113a0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
113b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
113c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
113d0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
113e0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
113f0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
11400 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
11410 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
11420 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11430 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
11440 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
11450 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
11460 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
11470 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
11480 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
11490 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
114a0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
114b0 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
114c0 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
114d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
114e0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
114f0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
11500 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
11510 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
11520 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
11530 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
11540 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
11550 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
11560 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
11570 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
11580 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
11590 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
115a0 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
115b0 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
115c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
115d0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
115e0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
115f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11600 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
11610 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
11620 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
11630 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
11640 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
11650 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
11660 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
11670 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
11680 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
11690 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
116a0 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
116b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
116c0 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
116d0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
116e0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
116f0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
11700 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
11710 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
11720 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
11730 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
11740 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
11750 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
11760 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
11770 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
11780 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
11790 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
117a0 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
117b0 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
117c0 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
117d0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
117e0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
117f0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
11800 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
11810 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
11820 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
11830 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
11840 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
11850 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
11860 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
11870 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
11880 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
11890 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
118a0 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
118b0 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
118c0 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
118d0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
118e0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
118f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
11900 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
11910 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
11920 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
11930 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
11940 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
11950 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
11960 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
11970 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
11980 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
11990 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
119a0 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
119b0 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
119c0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
119d0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
119e0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
119f0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
11a00 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
11a10 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11a20 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
11a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
11a40 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
11a50 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
11a60 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
11a70 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
11a80 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
11a90 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
11aa0 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
11ab0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
11ac0 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
11ad0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
11ae0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11af0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
11b00 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
11b10 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
11b20 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
11b30 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
11b40 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
11b50 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
11b60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
11b70 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
11b80 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
11b90 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
11ba0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
11bb0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
11bc0 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
11bd0 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
11be0 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
11bf0 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
11c00 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
11c10 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
11c20 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
11c30 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
11c40 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
11c50 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
11c60 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
11c70 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
11c80 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
11c90 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
11ca0 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
11cb0 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
11cc0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11cd0 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
11ce0 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
11cf0 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
11d00 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11d10 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
11d20 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
11d30 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
11d40 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
11d50 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
11d60 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
11d70 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
11d80 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
11d90 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
11da0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11db0 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
11dc0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
11dd0 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
11de0 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
11df0 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
11e00 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
11e10 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11e20 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
11e30 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
11e40 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11e50 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
11e60 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11e70 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
11e80 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
11e90 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
11ea0 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
11eb0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
11ec0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
11ed0 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
11ee0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11ef0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
11f00 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
11f10 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
11f20 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
11f30 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
11f40 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
11f50 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
11f60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
11f70 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
11f80 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
11f90 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
11fa0 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
11fb0 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
11fc0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
11fd0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
11fe0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11ff0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
12000 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
12010 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12020 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
12030 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
12040 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
12050 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
12060 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
12070 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
12080 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
12090 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
120a0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
120b0 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
120c0 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
120d0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
120e0 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
120f0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12100 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
12110 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
12120 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
12130 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
12140 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
12150 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
12160 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
12170 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
12180 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
12190 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
121a0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
121b0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
121c0 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
121d0 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
121e0 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
121f0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
12200 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
12210 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
12220 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
12230 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
12240 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
12250 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
12260 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
12270 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
12280 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
12290 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
122a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
122b0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
122c0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
122d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
122e0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
122f0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
12300 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12310 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
12320 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
12330 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
12340 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
12350 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
12360 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
12370 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
12380 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
12390 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
123a0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
123b0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
123c0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
123d0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
123e0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
123f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12400 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
12410 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
12420 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
12430 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12440 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
12450 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
12460 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
12470 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
12480 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
12490 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
124a0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
124b0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
124c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
124d0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
124e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
124f0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
12500 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12510 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12520 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12530 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
12540 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
12550 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12560 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
12570 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12580 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
12590 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
125a0 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
125b0 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
125c0 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
125d0 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
125e0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
125f0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12600 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12610 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12620 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
12630 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12640 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12650 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
12660 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
12670 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
12680 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
12690 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
126a0 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
126b0 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
126c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
126d0 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
126e0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
126f0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
12700 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
12710 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
12720 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12730 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12740 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12750 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
12760 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12770 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
12780 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12790 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
127a0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
127b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
127c0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
127d0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
127e0 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
127f0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
12800 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
12810 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
12820 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
12830 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12840 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
12850 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12860 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
12870 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
12880 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
12890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
128a0 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
128b0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
128c0 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
128d0 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
128e0 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
128f0 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
12900 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
12910 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
12920 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
12930 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
12940 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
12950 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
12960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12970 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
12980 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
12990 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
129a0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
129b0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
129c0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
129d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
129e0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
129f0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12a00 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
12a10 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
12a20 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12a30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12a40 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12a50 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12a60 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12a70 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
12a80 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
12a90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12aa0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12ab0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12ac0 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
12ad0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
12ae0 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
12af0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
12b00 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
12b10 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
12b20 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12b30 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
12b40 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
12b50 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
12b60 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
12b70 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
12b80 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
12b90 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
12ba0 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
12bb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12bc0 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12bd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12be0 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
12bf0 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
12c00 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
12c10 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
12c20 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
12c30 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12c40 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
12c50 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
12c60 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
12c70 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
12c80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12c90 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12ca0 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
12cb0 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
12cc0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
12cd0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
12ce0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12cf0 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
12d00 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
12d10 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
12d20 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
12d30 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
12d40 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
12d50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12d60 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12d70 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12d80 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12d90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12da0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12db0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12dc0 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
12dd0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
12de0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
12df0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12e00 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12e10 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12e20 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12e30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12e40 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
12e50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12e60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12e70 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12e80 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12e90 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
12ea0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
12eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12ec0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
12ed0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12ee0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
12ef0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12f00 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12f10 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12f20 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12f30 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
12f40 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12f50 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12f60 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12f70 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12f80 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
12f90 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
12fa0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12fb0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
12fc0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
12fd0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
12fe0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
12ff0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
13000 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
13010 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
13020 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
13030 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
13040 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
13050 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
13060 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13070 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
13080 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13090 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
130a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
130b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
130c0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
130d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
130e0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
130f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13100 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13110 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
13120 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13130 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
13140 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
13150 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
13160 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
13170 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
13180 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
13190 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
131a0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
131b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
131c0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
131d0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
131e0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
131f0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
13200 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
13210 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13220 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
13230 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
13240 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
13250 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
13260 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13270 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
13280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13290 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
132a0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
132b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
132c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
132d0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
132e0 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
132f0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
13300 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
13310 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
13320 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
13330 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
13340 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
13350 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
13360 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
13370 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
13380 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
13390 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
133a0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
133b0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
133c0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
133d0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
133e0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
133f0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13400 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
13410 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
13420 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
13430 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
13440 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
13450 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20  status64()].**  
13460 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
13470 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13480 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
13490 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
134a0 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
134b0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
134c0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
134d0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
134e0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
134f0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
13500 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13510 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
13520 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
13530 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13540 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
13550 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13560 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
13570 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
13580 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13590 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  H option specifi
135a0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
135b0 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  ry buffer.** tha
135c0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
135d0 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d   for scratch mem
135e0 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72  ory.  ^(There ar
135f0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13600 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43  s.** to SQLITE_C
13610 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20  ONFIG_SCRATCH:  
13620 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
13630 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
13640 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
13650 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
13660 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
13670 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
13680 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13690 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
136a0 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
136b0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
136c0 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
136d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
136e0 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .)^.** The first
136f0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13700 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
13710 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
13720 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
13730 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13740 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
13750 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74  ^SQLite will not
13760 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f   use more than o
13770 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
13780 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a  rs per thread..*
13790 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
137a0 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73  ever request a s
137b0 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
137c0 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
137d0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
137e0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
137f0 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
13800 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
13810 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
13820 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
13830 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13840 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
13850 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
13860 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
13870 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
13880 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
13890 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
138a0 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65  eded.<p>.** ^Whe
138b0 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
138c0 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61  n provides any a
138d0 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68  mount of scratch
138e0 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a   memory using.**
138f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13900 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61  CRATCH, SQLite a
13910 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72  voids unnecessar
13920 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69  y large.** [sqli
13930 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20  te3_malloc|heap 
13940 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a  allocations]..**
13950 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b   This can help [
13960 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65  Robson proof|pre
13970 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  vent memory allo
13980 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d  cation failures]
13990 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20   due to heap.** 
139a0 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  fragmentation in
139b0 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65   low-memory embe
139c0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  dded systems..**
139d0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
139e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
139f0 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  ECACHE]] <dt>SQL
13a00 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
13a10 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
13a20 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13a30 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f  NFIG_PAGECACHE o
13a40 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
13a50 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a  a memory pool.**
13a60 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13a70 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
13a80 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
13a90 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
13aa0 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
13ab0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
13ac0 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
13ad0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
13ae0 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20  s a no-op if an 
13af0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13b00 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
13b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13b20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
13b30 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
13b40 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20  IG_PCACHE2]..** 
13b50 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13b60 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13b80 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72  CACHE: A pointer
13b90 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c   to.** 8-byte al
13ba0 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d  igned memory (pM
13bb0 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  em), the size of
13bc0 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65   each page cache
13bd0 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61   line (sz),.** a
13be0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
13bf0 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29   cache lines (N)
13c00 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
13c10 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
13c20 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
13c30 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
13c40 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
13c50 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
13c60 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70  512 and 65536) p
13c70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62  lus some extra b
13c80 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ytes for each.**
13c90 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
13ca0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  The number of ex
13cb0 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64  tra bytes needed
13cc0 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61   by the page hea
13cd0 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  der.** can be de
13ce0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b  termined using [
13cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13d00 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20  ACHE_HDRSZ]..** 
13d10 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13d20 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13d30 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13d40 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
13d50 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
13d60 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
13d70 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a  ry.  The pMem.**
13d80 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13d90 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  e either a NULL 
13da0 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69  pointer or a poi
13db0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
13dc0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f  e.** aligned blo
13dd0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20  ck of memory of 
13de0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
13df0 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a  tes, otherwise.*
13e00 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  * subsequent beh
13e10 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
13e20 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65  ed..** ^When pMe
13e30 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  m is not NULL, S
13e40 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76  QLite will striv
13e50 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d  e to use the mem
13e60 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ory provided.** 
13e70 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20  to satisfy page 
13e80 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c  cache needs, fal
13e90 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71  ling back to [sq
13ea0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13eb0 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63  if.** a page cac
13ec0 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65  he line is large
13ed0 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20  r than sz bytes 
13ee0 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65  or if all of the
13ef0 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20   pMem buffer.** 
13f00 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  is exhausted..**
13f10 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c   ^If pMem is NUL
13f20 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a  L and N is non-z
13f30 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64  ero, then each d
13f40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13f50 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e  on.** does an in
13f60 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63  itial bulk alloc
13f70 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63  ation for page c
13f80 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66  ache memory.** f
13f90 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
13fa0 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e  loc()] sufficien
13fb0 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69  t for N cache li
13fc0 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69  nes if N is posi
13fd0 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31  tive or.** of -1
13fe0 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e  024*N bytes if N
13ff0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20   is negative, . 
14000 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
14010 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
14020 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
14030 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
14040 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69  vided by the ini
14050 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  tial.** allocati
14060 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  on, then SQLite 
14070 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
14080 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72  _malloc()] separ
14090 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a  ately for each.*
140a0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63  * additional cac
140b0 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a  he line. </dd>.*
140c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
140d0 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
140e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
140f0 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
14100 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14110 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73  IG_HEAP option s
14120 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
14130 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
14140 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
14150 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c  will use for all
14160 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
14170 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14180 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e  n needs.** beyon
14190 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
141a0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
141b0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
141c0 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  and.** [SQLITE_C
141d0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
141e0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
141f0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
14200 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14210 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
14220 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
14230 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
14240 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
14250 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
14260 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
14270 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
14280 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
14290 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
142a0 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
142b0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
142c0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
142d0 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
142e0 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
142f0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
14300 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
14310 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
14320 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
14330 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
14340 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
14350 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
14360 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14370 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
14380 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
14390 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
143a0 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
143b0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
143c0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
143d0 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
143e0 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
143f0 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
14400 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
14410 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
14420 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
14430 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
14440 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
14450 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
14460 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
14470 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
14480 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
14490 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
144a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
144b0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
144c0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
144d0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
144e0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
144f0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
14500 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
14510 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
14520 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
14530 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
14540 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
14550 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
14560 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
14570 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
14580 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
14590 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
145a0 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
145b0 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
145c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
145d0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
145e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
145f0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
14600 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14610 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
14620 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14630 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14640 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
14650 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14660 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14670 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14680 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
14690 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
146a0 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
146b0 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
146c0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
146d0 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
146e0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
146f0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
14700 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
14710 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
14720 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
14730 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14740 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14750 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
14760 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
14770 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14780 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
14790 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
147a0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
147b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
147c0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
147d0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
147e0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
147f0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
14800 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
14810 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14820 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14830 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14840 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14850 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14860 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14870 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14880 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14890 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
148a0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
148b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
148c0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
148d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
148e0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
148f0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14900 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
14910 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14920 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14930 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
14940 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14950 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14960 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14970 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
14980 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
14990 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
149a0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
149b0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
149c0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
149d0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
149e0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
149f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14a00 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
14a10 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
14a20 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14a30 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14a40 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
14a50 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
14a60 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
14a70 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
14a80 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
14a90 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
14aa0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14ab0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
14ac0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
14ad0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
14ae0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14af0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
14b00 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
14b10 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
14b20 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
14b30 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
14b40 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
14b50 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
14b60 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
14b70 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
14b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14b90 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
14ba0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
14bb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14bd0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
14be0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14bf0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
14c00 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14c10 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
14c20 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
14c30 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
14c40 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
14c50 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
14c60 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14c70 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
14c80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
14c90 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
14ca0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
14cb0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
14cc0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
14cd0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
14ce0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
14cf0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
14d00 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
14d10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14d20 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
14d30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
14d40 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
14d50 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
14d60 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
14d70 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14d80 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
14d90 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
14da0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
14db0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
14dc0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
14dd0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
14de0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
14df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
14e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14e20 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
14e30 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
14e40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14e50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14e60 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
14e70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14e80 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14e90 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
14ea0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
14eb0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14ec0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
14ed0 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
14ee0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
14ef0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
14f00 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
14f10 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
14f20 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
14f30 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14f40 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14f50 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
14f60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14f70 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
14f80 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14f90 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
14fa0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14fb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14fc0 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
14fd0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14fe0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
14ff0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
15000 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
15010 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
15020 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
15030 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
15040 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
15050 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15060 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
15070 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
15080 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15090 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
150a0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
150b0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
150c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
150d0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
150e0 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
150f0 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
15100 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
15110 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
15120 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15130 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
15140 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
15150 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
15160 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
15170 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
15180 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15190 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
151a0 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
151b0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
151c0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
151d0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
151e0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
151f0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15200 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15210 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15220 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
15230 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
15240 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
15250 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
15260 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
15270 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
15280 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
15290 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
152a0 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
152b0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
152c0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
152d0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
152e0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
152f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15300 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15310 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
15320 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
15330 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
15340 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
15350 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
15360 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
15370 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
15380 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
15390 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
153a0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
153b0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
153c0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
153d0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
153e0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
153f0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
15400 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15410 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
15420 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
15430 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
15440 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
15450 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15460 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
15470 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
15480 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
15490 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
154a0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
154b0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
154c0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
154d0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
154e0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
154f0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
15500 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
15510 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
15520 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
15530 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
15540 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
15550 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
15560 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15570 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
15580 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
15590 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
155a0 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
155b0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
155c0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
155d0 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
155e0 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
155f0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15600 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
15610 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
15620 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
15630 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15640 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
15650 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
15660 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
15670 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
15680 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
15690 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
156a0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
156b0 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
156c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
156d0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
156e0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
156f0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
15700 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
15710 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
15720 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
15730 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
15740 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
15750 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
15760 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
15770 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
15780 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
15790 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
157a0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
157b0 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
157c0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
157d0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
157e0 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
157f0 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
15800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
15810 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
15820 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
15830 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
15840 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
15850 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
15860 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
15870 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
15880 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
15890 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
158a0 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
158b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
158c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
158d0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
158e0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
158f0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
15900 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
15910 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15920 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
15930 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15940 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
15950 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
15960 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
15970 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
15980 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
15990 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
159a0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
159b0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
159c0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
159d0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
159e0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
159f0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
15a00 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
15a10 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
15a20 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15a30 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
15a40 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
15a50 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
15a60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15a70 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
15a80 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
15a90 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
15aa0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
15ab0 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
15ac0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
15ad0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
15ae0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
15af0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
15b00 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
15b10 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
15b20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
15b30 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
15b40 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
15b50 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
15b60 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
15b70 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
15b80 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
15b90 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
15ba0 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
15bb0 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
15bc0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
15bd0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
15be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15bf0 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
15c00 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
15c10 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15c20 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
15c30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15c40 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
15c50 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
15c60 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
15c70 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
15c80 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
15c90 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
15ca0 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
15cb0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15cc0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
15cd0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
15ce0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15cf0 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
15d00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15d10 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
15d20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
15d30 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
15d40 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
15d50 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
15d60 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
15d70 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
15d80 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
15d90 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
15da0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
15db0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
15dc0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
15dd0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
15de0 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
15df0 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
15e00 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
15e10 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
15e20 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
15e30 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
15e40 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
15e50 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
15e60 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
15e70 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
15e80 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
15e90 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
15ea0 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
15eb0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15ec0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
15ed0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
15ee0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
15ef0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15f00 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
15f10 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
15f20 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
15f30 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
15f40 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
15f50 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
15f60 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
15f70 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
15f80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15f90 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
15fa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
15fb0 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
15fc0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
15fd0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
15fe0 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
15ff0 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
16000 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
16010 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
16020 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
16030 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16040 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
16050 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
16060 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
16070 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
16080 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
16090 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
160a0 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
160b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
160c0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
160d0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
160e0 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
160f0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
16100 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
16110 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
16120 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16130 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
16140 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16150 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
16160 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
16170 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
16180 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
16190 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
161a0 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
161b0 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
161c0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
161d0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
161e0 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
161f0 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
16200 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
16210 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16220 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
16230 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
16240 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
16250 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
16260 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
16270 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
16280 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
16290 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
162a0 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
162b0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
162c0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
162d0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
162e0 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
162f0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16300 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
16310 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
16320 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
16330 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
16340 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
16350 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
16360 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
16370 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
16380 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
16390 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
163a0 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
163b0 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
163c0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
163d0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
163e0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
163f0 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
16400 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
16410 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
16420 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16430 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
16440 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16450 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16460 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
16470 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
16480 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
16490 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
164a0 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
164b0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
164c0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
164d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
164e0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
164f0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
16500 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
16510 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16520 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
16530 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
16540 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
16550 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
16560 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
16570 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
16580 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
16590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
165a0 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
165b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
165c0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
165d0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
165e0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
165f0 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
16600 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
16610 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16620 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16630 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
16640 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
16650 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
16660 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
16670 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
16680 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
16690 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
166a0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
166b0 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
166c0 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
166d0 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
166e0 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
166f0 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
16700 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
16710 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
16720 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
16730 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
16740 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16750 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
16760 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16770 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
16780 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16790 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
167a0 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
167b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
167c0 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
167d0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
167e0 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
167f0 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
16800 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
16810 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
16820 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
16830 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
16840 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
16850 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
16860 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
16870 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
16880 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
16890 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
168a0 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
168b0 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
168c0 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
168d0 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
168e0 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
168f0 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
16900 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
16910 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
16920 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
16930 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
16940 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
16950 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
16960 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
16970 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b  s value..**.** [
16980 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
16990 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a  TMTJRNL_SPILL]].
169a0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
169b0 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
169c0 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ILL.** <dd>^The 
169d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
169e0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74  MTJRNL_SPILL opt
169f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
16a00 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
16a10 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68  ch.** becomes th
16a20 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  e [statement jou
16a30 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64  rnal] spill-to-d
16a40 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20  isk threshold.  
16a50 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a  .** [Statement j
16a60 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c  ournals] are hel
16a70 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69  d in memory unti
16a80 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e  l their size (in
16a90 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65   bytes).** excee
16aa0 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c  ds this threshol
16ab0 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e  d, at which poin
16ac0 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74  t they are writt
16ad0 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f  en to disk..** O
16ae0 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f  r if the thresho
16af0 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d  ld is -1, statem
16b00 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65  ent journals are
16b10 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20   always held.** 
16b20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d  exclusively in m
16b30 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20  emory..** Since 
16b40 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a  many statement j
16b50 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65  ournals never be
16b60 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74  come large, sett
16b70 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a  ing the spill.**
16b80 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20   threshold to a 
16b90 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34  value such as 64
16ba0 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20  KiB can greatly 
16bb0 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e  reduce the amoun
16bc0 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75  t of.** I/O requ
16bd0 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ired to support 
16be0 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61  statement rollba
16bf0 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ck..** The defau
16c00 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69  lt value for thi
16c10 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e  s setting is con
16c20 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a  trolled by the.*
16c30 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52  * [SQLITE_STMTJR
16c40 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c  NL_SPILL] compil
16c50 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
16c60 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
16c70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16c80 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
16c90 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16ca0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16cb0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
16cc0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
16cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16ce0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
16cf0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
16d00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16d10 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
16d20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
16d30 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d50 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
16d60 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
16d70 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16d80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d90 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
16da0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
16db0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16de0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
16df0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16e00 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
16e20 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
16e30 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
16e40 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
16e50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16e60 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
16e70 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
16e80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16e90 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
16ea0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
16eb0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16ec0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16ee0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
16ef0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16f00 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
16f10 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
16f20 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
16f30 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
16f40 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
16f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16f60 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16f70 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
16f80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f90 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
16fa0 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
16fb0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16fc0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16fd0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
16fe0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
16ff0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17000 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
17010 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
17020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17030 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
17040 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
17050 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17060 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
17070 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
17080 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
17090 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
170a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
170b0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
170c0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
170d0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
170e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
170f0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
17100 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
17110 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
17130 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
17140 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
17150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17160 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
17170 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
17180 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
17190 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
171a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
171b0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
171c0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
171d0 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
171e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
171f0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20  _PCACHE_HDRSZ   
17200 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20       24  /* int 
17210 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  *psz */.#define 
17220 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
17230 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20  ASZ             
17240 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65    25  /* unsigne
17250 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23  d int szPma */.#
17260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17270 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
17280 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20  ILL      26  /* 
17290 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a  int nByte */../*
172a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
172b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
172c0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
172d0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
172e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
172f0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
17300 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
17310 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
17320 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
17330 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17340 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
17350 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17360 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17370 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
17380 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17390 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
173a0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
173b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
173c0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
173d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
173e0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
173f0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
17400 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
17410 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
17420 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
17430 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17440 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
17450 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
17460 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
17470 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17480 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
17490 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
174a0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
174b0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
174c0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
174d0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
174e0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
174f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
17500 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
17510 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17520 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
17530 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
17540 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
17550 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
17560 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
17570 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
17580 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
17590 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
175a0 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
175b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
175c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
175d0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
175e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
175f0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
17600 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
17610 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
17620 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
17630 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
17640 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
17650 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
17660 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
17670 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17680 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
17690 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
176a0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
176b0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
176c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
176d0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
176e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
176f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
17700 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
17710 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
17720 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
17730 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
17740 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
17750 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
17760 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
17770 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
17780 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17790 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
177a0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
177b0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
177c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
177d0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
177e0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
177f0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
17800 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
17810 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
17820 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17830 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
17840 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
17850 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
17860 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
17870 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
17880 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
17890 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
178a0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
178b0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
178c0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
178d0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
178e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
178f0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
17900 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
17910 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
17920 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
17930 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
17940 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
17950 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
17960 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
17970 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
17980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
17990 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
179a0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
179b0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
179c0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
179d0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
179e0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
179f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
17a00 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
17a10 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
17a20 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
17a30 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
17a40 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
17a50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
17a60 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
17a70 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17a80 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
17a90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17aa0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17ab0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17ac0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
17ad0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
17ae0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
17af0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
17b00 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17b10 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17b20 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17b30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17b40 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17b50 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
17b60 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
17b70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
17b80 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
17b90 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
17ba0 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
17bb0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
17bc0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
17bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17be0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17bf0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17c00 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17c10 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17c20 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
17c30 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
17c40 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
17c50 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17c60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17c70 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17c80 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
17c90 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
17ca0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
17cb0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17cc0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
17cd0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17ce0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17cf0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
17d00 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17d10 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17d20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17d30 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
17d40 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
17d50 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17d60 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17d70 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17d80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17d90 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
17da0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
17db0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
17dc0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17dd0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
17de0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17df0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
17e00 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
17e10 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17e20 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
17e30 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
17e40 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
17e50 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
17e60 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
17e70 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
17e80 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17e90 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17ea0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17eb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17ec0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17ed0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17ee0 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
17ef0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
17f00 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17f10 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17f20 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
17f30 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
17f40 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
17f50 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17f60 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17f70 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17f80 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
17f90 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
17fa0 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
17fb0 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
17fc0 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
17fd0 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
17fe0 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
17ff0 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
18000 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18010 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18020 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18030 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18040 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18050 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18060 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
18070 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
18080 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
18090 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
180a0 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
180b0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
180c0 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
180d0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
180e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
180f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18100 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18110 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18120 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18130 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
18140 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
18150 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
18160 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
18170 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
18180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
18190 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
181a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
181b0 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
181c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
181d0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
181e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
181f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18200 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18210 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18220 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18230 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18240 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
18250 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18260 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
18270 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
18280 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
18290 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
182a0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
182b0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
182c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
182d0 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
182e0 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
182f0 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
18300 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18310 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
18320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
18330 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
18340 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18350 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18360 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18370 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
18380 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
18390 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
183a0 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
183b0 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
183c0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
183d0 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
183e0 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
183f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18400 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
18410 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
18420 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
18430 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18440 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
18450 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
18460 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
18470 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
18480 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
18490 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
184a0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
184b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
184c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
184d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
184e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
184f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18500 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18510 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18520 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
18530 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18540 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
18550 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
18560 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
18570 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18580 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18590 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
185a0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
185b0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
185c0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
185d0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
185e0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
185f0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18600 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
18610 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18620 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18630 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
18640 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
18650 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
18660 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
18670 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
18680 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
18690 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
186a0 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
186b0 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
186c0 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
186d0 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
186e0 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
186f0 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
18700 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
18710 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
18720 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
18730 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
18740 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
18750 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
18760 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
18770 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
18780 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
18790 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
187a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
187b0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
187c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
187d0 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
187e0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
187f0 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
18800 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
18810 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
18820 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
18830 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
18840 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
18850 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
18860 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
18870 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
18880 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
18890 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
188a0 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
188b0 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
188c0 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
188d0 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
188e0 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
188f0 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
18900 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
18910 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
18920 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
18930 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18940 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
18950 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
18960 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e  an integer - non
18970 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65  -zero to disable
18980 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
18990 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
189a0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
189b0 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20  to enable them. 
189c0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
189d0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
189e0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
189f0 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
18a00 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18a10 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18a20 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
18a30 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
18a40 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
18a50 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
18a60 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
18a70 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
18a80 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
18a90 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18aa0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e  TE_DBCONFIG_MAIN
18ab0 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  DBNAME          
18ac0 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20    1000 /* const 
18ad0 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  char* */.#define
18ae0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18af0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
18b00 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76         1001 /* v
18b10 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
18b20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18b30 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18b40 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30  KEY           10
18b50 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  02 /* int int* *
18b60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18b70 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18b80 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
18b90 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1003 /* int int*
18ba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18bb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18bc0 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45  LE_FTS3_TOKENIZE
18bd0 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e  R 1004 /* int in
18be0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18bf0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18c00 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
18c10 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20  ION 1005 /* int 
18c20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18c30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18c40 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
18c50 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e        1006 /* in
18c60 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
18c70 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
18c80 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
18c90 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
18ca0 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
18cb0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
18cc0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
18cd0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
18ce0 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
18cf0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
18d00 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
18d10 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
18d20 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
18d30 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
18d40 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
18d50 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
18d60 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
18d70 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
18d80 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
18d90 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
18da0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
18db0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
18dc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18dd0 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
18de0 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
18df0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
18e00 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
18e10 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
18e20 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
18e30 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
18e40 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
18e50 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
18e60 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
18e70 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
18e80 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
18e90 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
18ea0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
18eb0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
18ec0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
18ed0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
18ee0 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
18ef0 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
18f00 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
18f10 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
18f20 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
18f30 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
18f40 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
18f50 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
18f60 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
18f70 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
18f80 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
18f90 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
18fa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18fb0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
18fc0 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
18fd0 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
18fe0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
18ff0 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
19000 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
19010 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
19020 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
19030 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
19040 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
19050 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
19060 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
19070 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
19080 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
19090 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
190a0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
190b0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
190c0 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
190d0 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
190e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
190f0 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
19100 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19110 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
19120 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
19130 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
19140 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
19150 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
19160 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
19170 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
19180 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
19190 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
191a0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
191b0 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
191c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
191d0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
191e0 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
191f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
19200 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
19210 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
19220 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
19230 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
19240 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
19250 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
19260 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
19270 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
19280 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
19290 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
192a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
192b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
192c0 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
192d0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
192e0 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
192f0 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
19300 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
19310 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
19320 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
19330 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
19340 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
19350 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
19360 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
19370 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
19380 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
19390 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
193a0 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
193b0 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
193c0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
193d0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
193e0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
193f0 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
19400 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
19410 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
19420 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
19430 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
19440 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
19450 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
19460 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
19470 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
19480 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
19490 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
194a0 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
194b0 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
194c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
194d0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
194e0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
194f0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
19500 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
19510 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
19520 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
19530 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
19540 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
19550 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
19560 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
19570 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
19580 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
19590 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
195a0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
195b0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
195c0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
195d0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
195e0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
195f0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
19600 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
19610 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
19620 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19630 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
19640 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
19650 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
19660 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
19670 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
19680 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
19690 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
196a0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
196b0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
196c0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
196d0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
196e0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
196f0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
19700 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
19710 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
19720 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
19730 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
19740 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
19750 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
19760 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
19770 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
19780 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
19790 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
197a0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
197b0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
197c0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
197d0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
197e0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
197f0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
19800 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
19810 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
19820 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19830 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
19840 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
19850 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
19860 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
19870 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
19880 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
19890 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
198a0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
198b0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
198c0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
198d0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
198e0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
198f0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
19900 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
19910 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
19920 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
19930 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
19940 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
19950 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
19960 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
19970 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
19980 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19990 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
199a0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
199b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
199c0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
199d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
199e0 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74   the Last Insert
199f0 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a   Rowid value..**
19a00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19a10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
19a20 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
19a30 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d  rt_rowid(D, R) m
19a40 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65  ethod allows the
19a50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
19a60 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ** set the value
19a70 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c   returned by cal
19a80 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73  ling sqlite3_las
19a90 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
19aa0 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f  ) to R .** witho
19ab0 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72  ut inserting a r
19ac0 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ow into the data
19ad0 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  base..*/.void sq
19ae0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
19af0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
19b00 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
19b10 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
19b20 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
19b30 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
19b40 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
19b50 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19b60 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
19b70 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
19b80 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
19b90 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
19ba0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
19bb0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
19bc0 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
19bd0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
19be0 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
19bf0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
19c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
19c10 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
19c20 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
19c30 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
19c40 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
19c50 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
19c60 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
19c70 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
19c80 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
19c90 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
19ca0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
19cb0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
19cc0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
19cd0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
19ce0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
19cf0 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
19d00 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
19d10 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
19d20 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
19d30 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
19d40 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
19d50 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
19d60 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
19d70 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
19d80 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
19d90 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
19da0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
19db0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
19dc0 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
19dd0 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
19de0 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
19df0 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
19e00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
19e10 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
19e20 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
19e30 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
19e40 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
19e50 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
19e60 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
19e70 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
19e80 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
19e90 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
19ea0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
19eb0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
19ec0 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
19ed0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
19ee0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
19ef0 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
19f00 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
19f10 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
19f20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
19f30 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
19f40 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
19f50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
19f60 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
19f70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
19f80 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
19f90 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
19fa0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
19fb0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
19fc0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
19fd0 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
19fe0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19ff0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a000 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1a010 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a020 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1a030 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1a040 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1a050 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1a060 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1a070 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1a080 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1a090 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1a0a0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1a0b0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1a0c0 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1a0d0 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1a0e0 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1a0f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a100 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1a110 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1a120 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1a130 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1a140 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1a150 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1a160 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1a170 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1a180 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1a190 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1a1a0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1a1b0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1a1c0 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1a1d0 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1a1e0 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1a1f0 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1a200 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1a210 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1a220 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1a230 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1a240 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1a250 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1a260 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1a270 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1a280 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1a290 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1a2a0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1a2b0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1a2c0 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1a2d0 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1a2e0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1a2f0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1a300 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1a310 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1a320 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1a330 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1a340 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1a350 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1a360 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1a370 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1a380 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1a390 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1a3a0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1a3b0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1a3c0 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
1a3d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1a3e0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1a3f0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1a400 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1a410 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1a420 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1a430 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1a440 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1a450 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1a460 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1a470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a480 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1a490 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a4a0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1a4b0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1a4c0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1a4d0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1a4e0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1a4f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
1a500 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1a510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a520 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1a530 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1a540 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a550 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1a560 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1a570 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1a580 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1a590 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1a5a0 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1a5b0 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1a5c0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1a5d0 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1a5e0 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1a5f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a600 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1a610 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1a620 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1a630 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1a640 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1a650 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1a660 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1a670 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1a680 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1a690 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1a6a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a6b0 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1a6c0 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1a6d0 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1a6e0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1a6f0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1a700 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1a710 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1a720 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1a730 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1a740 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1a750 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1a760 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1a770 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1a780 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1a790 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1a7a0 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
1a7b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1a7c0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1a7d0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1a7e0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1a7f0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1a800 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1a810 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1a820 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1a830 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1a840 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1a850 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a860 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1a870 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a880 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1a890 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1a8a0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1a8b0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1a8c0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1a8d0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1a8e0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a8f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1a900 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1a910 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1a920 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1a930 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a940 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1a950 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1a960 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1a970 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1a980 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1a990 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1a9a0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1a9b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1a9c0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1a9d0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1a9e0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1a9f0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1aa00 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1aa10 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1aa20 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1aa30 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1aa40 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1aa50 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1aa60 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1aa70 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1aa80 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1aa90 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1aaa0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1aab0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1aac0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1aad0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1aae0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1aaf0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1ab00 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1ab10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ab20 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1ab30 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1ab40 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1ab50 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1ab60 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1ab70 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1ab80 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1ab90 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1aba0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1abb0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1abc0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1abd0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1abe0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1abf0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1ac00 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1ac10 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1ac20 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1ac30 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1ac40 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1ac50 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1ac60 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1ac70 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1ac80 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1ac90 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1aca0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1acb0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1acc0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1acd0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1ace0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1acf0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1ad00 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1ad10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1ad20 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1ad30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1ad40 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1ad50 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1ad60 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1ad70 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1ad80 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1ad90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ada0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1adb0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1adc0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1add0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1ade0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1adf0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1ae00 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1ae10 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1ae20 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1ae30 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1ae40 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1ae50 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1ae60 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1ae70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ae80 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1ae90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1aea0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1aeb0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1aec0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1aed0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1aee0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1aef0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1af00 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1af10 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1af20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1af30 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1af40 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1af50 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1af60 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1af70 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1af80 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1af90 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1afa0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1afb0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1afc0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1afd0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  ll returns..*/.v
1afe0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1aff0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1b000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b010 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1b020 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1b030 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1b040 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b050 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1b060 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1b070 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1b080 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1b090 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1b0a0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1b0b0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1b0c0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1b0d0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1b0e0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1b0f0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1b100 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1b110 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1b120 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1b130 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1b140 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1b150 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1b160 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1b170 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1b180 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1b190 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1b1a0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1b1b0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1b1c0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1b1d0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1b1e0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1b1f0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1b200 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1b210 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1b220 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1b230 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1b240 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1b250 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1b260 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1b270 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1b280 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1b290 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1b2a0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1b2b0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1b2c0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1b2d0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1b2e0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1b2f0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1b300 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1b310 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1b320 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1b330 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1b340 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1b350 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1b360 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1b370 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1b380 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1b390 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1b3a0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1b3b0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1b3c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1b3d0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1b3e0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1b3f0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1b400 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1b410 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1b420 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1b430 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1b440 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1b450 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1b460 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1b470 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1b480 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1b490 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1b4a0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1b4b0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1b4c0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1b4d0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1b4e0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1b4f0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1b500 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1b510 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1b520 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1b530 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1b540 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1b550 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1b560 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1b570 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1b580 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1b590 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1b5a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b5b0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1b5c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1b5d0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1b5e0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b5f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b600 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1b610 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1b620 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1b630 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1b640 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1b650 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b660 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1b670 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1b680 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1b690 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1b6a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1b6b0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1b6c0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1b6d0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1b6e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1b6f0 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1b700 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1b710 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1b720 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1b730 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1b740 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1b750 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1b760 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1b770 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1b780 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1b790 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1b7a0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1b7b0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1b7c0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1b7d0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1b7e0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1b7f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1b800 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1b810 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1b820 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1b830 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1b840 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1b850 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1b860 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1b870 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1b880 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1b890 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1b8a0 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1b8b0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1b8c0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1b8d0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1b8e0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1b8f0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1b900 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1b910 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1b920 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1b930 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1b940 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1b950 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1b960 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1b970 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1b980 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1b990 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1b9a0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1b9b0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1b9c0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1b9d0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1b9e0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1b9f0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1ba00 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1ba10 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1ba20 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1ba30 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1ba40 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1ba50 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1ba60 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1ba70 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1ba80 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1ba90 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1baa0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1bab0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1bac0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1bad0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1bae0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1baf0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1bb00 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1bb10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1bb20 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1bb30 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1bb40 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1bb50 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1bb60 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1bb70 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1bb80 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1bb90 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1bba0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1bbb0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1bbc0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1bbd0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1bbe0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1bbf0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1bc00 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1bc10 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1bc20 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1bc30 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1bc40 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1bc50 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1bc60 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1bc70 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1bc80 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1bc90 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1bca0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1bcb0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1bcc0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1bcd0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1bce0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1bcf0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1bd00 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1bd10 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1bd20 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1bd30 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1bd40 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1bd50 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1bd60 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1bd70 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1bd80 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1bd90 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1bda0 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1bdb0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1bdc0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1bdd0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1bde0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1bdf0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1be00 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1be10 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1be20 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1be30 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1be40 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1be50 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1be60 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1be70 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1be80 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1be90 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1bea0 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1beb0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1bec0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1bed0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1bee0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1bef0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1bf00 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1bf10 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1bf20 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1bf30 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1bf40 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1bf50 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1bf60 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1bf70 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1bf80 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1bf90 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1bfa0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1bfb0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1bfc0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1bfd0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1bfe0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1bff0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1c000 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1c010 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1c020 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1c030 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1c040 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1c050 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1c060 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c070 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1c080 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1c090 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1c0a0 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1c0b0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1c0c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1c0d0 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1c0e0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1c0f0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1c100 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1c110 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c120 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1c130 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1c140 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1c150 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c160 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1c170 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1c180 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1c190 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1c1a0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1c1b0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1c1c0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1c1d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c1e0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1c1f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c200 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1c210 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1c220 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1c230 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1c240 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1c250 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1c260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c270 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1c280 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1c290 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1c2a0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1c2b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1c2c0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1c2d0 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1c2e0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1c2f0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1c300 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1c310 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1c320 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1c330 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1c340 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1c350 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1c360 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1c370 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1c380 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1c390 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1c3a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1c3b0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1c3c0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1c3d0 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1c3e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c3f0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1c400 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1c410 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1c420 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1c430 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1c440 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1c450 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1c460 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1c470 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1c480 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c490 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c4a0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1c4b0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1c4c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1c4d0 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1c4e0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1c4f0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1c500 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1c510 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1c520 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1c530 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1c540 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1c550 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1c560 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1c570 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1c580 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1c590 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1c5a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1c5b0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1c5c0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1c5d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1c5e0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1c5f0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1c600 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1c610 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1c620 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1c630 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1c640 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1c650 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1c660 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1c670 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1c680 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1c690 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1c6a0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1c6b0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1c6c0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1c6d0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1c6e0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1c6f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1c700 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1c710 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1c720 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1c730 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1c740 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1c750 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1c760 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1c770 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1c780 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1c790 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1c7a0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1c7b0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1c7c0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1c7d0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1c7e0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1c7f0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1c800 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1c810 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1c820 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1c830 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1c840 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1c850 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1c860 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1c870 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1c880 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1c890 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1c8a0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1c8b0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1c8c0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1c8d0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1c8e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1c8f0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1c900 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1c910 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1c920 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1c930 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1c940 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1c950 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1c960 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1c970 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1c980 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1c990 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1c9a0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1c9b0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1c9c0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1c9d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1c9e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1c9f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1ca00 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1ca10 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1ca20 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1ca30 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1ca40 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1ca50 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1ca60 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1ca70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1ca80 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1ca90 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1caa0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1cab0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1cac0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1cad0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1cae0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1caf0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1cb00 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1cb10 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1cb20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1cb30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1cb40 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1cb50 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1cb60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1cb70 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1cb80 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1cb90 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1cba0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1cbb0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1cbc0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1cbd0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1cbe0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1cbf0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1cc00 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1cc10 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1cc20 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1cc30 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1cc40 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1cc50 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1cc60 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1cc70 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1cc80 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1cc90 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1cca0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1ccb0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ccc0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ccd0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1cce0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1ccf0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1cd00 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1cd10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1cd20 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1cd30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cd40 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1cd50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cd60 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1cd70 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1cd80 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1cd90 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1cda0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1cdb0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1cdc0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1cdd0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1cde0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1cdf0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1ce00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1ce10 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1ce20 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1ce30 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1ce40 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1ce50 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1ce60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1ce70 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1ce80 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1ce90 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1cea0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1ceb0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1cec0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1ced0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1cee0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1cef0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1cf00 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1cf10 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1cf20 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1cf30 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1cf40 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1cf50 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1cf60 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1cf70 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1cf80 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1cf90 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1cfa0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1cfb0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1cfc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1cfd0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1cfe0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1cff0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1d000 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1d010 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1d020 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1d030 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1d040 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1d050 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1d060 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1d070 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1d080 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1d090 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1d0a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1d0b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1d0c0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1d0d0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1d0e0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1d0f0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1d100 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1d110 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1d120 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1d130 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1d140 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1d150 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1d160 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1d170 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1d180 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1d190 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1d1a0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1d1b0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1d1c0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1d1d0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1d1e0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1d1f0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1d200 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1d210 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1d220 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1d230 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1d240 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1d250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1d260 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1d270 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1d280 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1d290 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1d2a0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1d2b0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1d2c0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1d2d0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1d2e0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1d2f0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1d300 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1d310 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1d320 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1d330 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1d340 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1d350 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1d360 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1d370 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1d380 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1d390 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1d3a0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1d3b0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1d3c0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d3d0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1d3e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d3f0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1d400 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1d410 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1d420 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1d430 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1d440 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1d450 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1d460 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1d470 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1d480 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1d490 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1d4a0 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1d4b0 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1d4c0 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1d4d0 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1d4e0 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1d4f0 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1d500 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1d510 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1d520 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1d530 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1d540 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1d550 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1d560 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1d570 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1d580 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1d590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1d5a0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1d5b0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1d5c0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1d5d0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1d5e0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1d5f0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1d600 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1d610 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1d620 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1d630 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1d640 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1d650 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1d660 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1d670 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1d680 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1d690 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d6a0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1d6b0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1d6c0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1d6d0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1d6e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1d6f0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1d700 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1d710 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1d720 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1d730 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1d740 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1d750 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1d760 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1d770 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1d780 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1d790 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1d7a0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1d7b0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1d7c0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1d7d0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1d7e0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1d7f0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1d800 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1d810 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1d820 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1d830 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1d840 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1d850 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1d860 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1d870 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1d880 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1d890 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1d8a0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1d8b0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1d8c0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1d8d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1d8e0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1d8f0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1d900 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1d910 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1d920 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1d930 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1d940 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1d950 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1d960 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1d970 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1d980 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1d990 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1d9a0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1d9b0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1d9c0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1d9d0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1d9e0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1d9f0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1da00 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1da10 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1da20 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1da30 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1da40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1da50 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1da60 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1da70 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1da80 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1da90 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1daa0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1dab0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1dac0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1dad0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1dae0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1daf0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1db00 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1db10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1db20 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1db30 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1db40 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1db50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1db60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1db70 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1db80 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1db90 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1dba0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1dbb0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1dbc0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1dbd0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1dbe0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1dbf0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1dc00 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1dc10 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1dc20 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1dc30 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1dc40 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1dc50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1dc60 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1dc70 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1dc80 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1dc90 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1dca0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1dcb0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1dcc0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1dcd0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1dce0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1dcf0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1dd00 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1dd10 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1dd20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1dd30 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1dd40 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1dd50 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1dd60 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1dd70 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1dd80 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1dd90 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1dda0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1ddb0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1ddc0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1ddd0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1dde0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ddf0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1de00 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1de10 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1de20 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1de30 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1de40 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1de50 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1de60 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1de70 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1de80 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1de90 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1dea0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1deb0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1dec0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1ded0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1dee0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1def0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1df00 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1df10 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1df20 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1df30 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1df40 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1df50 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1df60 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1df70 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1df80 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1df90 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1dfa0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1dfb0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1dfc0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1dfd0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1dfe0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1dff0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e000 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1e010 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1e020 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1e030 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1e040 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1e050 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1e060 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1e070 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1e080 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1e090 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1e0a0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1e0b0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1e0c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e0d0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1e0e0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1e0f0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1e100 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1e110 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1e120 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1e130 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1e140 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1e150 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1e160 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1e170 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1e180 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1e190 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1e1a0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1e1b0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1e1c0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1e1d0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1e1e0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1e1f0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1e200 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1e210 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1e220 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1e230 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1e240 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1e250 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1e260 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1e270 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1e280 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1e290 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1e2a0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1e2b0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1e2c0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1e2d0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1e2e0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1e2f0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1e300 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1e310 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1e320 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e330 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1e340 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1e350 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1e360 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1e370 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1e380 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1e390 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1e3a0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1e3b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1e3c0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1e3d0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1e3e0 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1e3f0 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1e400 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1e410 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1e420 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1e430 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1e440 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1e450 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1e460 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1e470 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1e480 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1e490 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1e4a0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1e4b0 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1e4c0 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1e4d0 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1e4e0 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1e4f0 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1e500 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1e510 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1e520 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1e530 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1e540 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1e550 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1e560 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1e570 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1e580 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1e590 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1e5a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e5b0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1e5c0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1e5d0 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1e5e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1e5f0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1e600 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1e610 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1e620 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1e630 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1e640 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1e650 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1e660 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1e670 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1e680 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1e690 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1e6a0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1e6b0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1e6c0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1e6d0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1e6e0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1e6f0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1e700 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1e710 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1e720 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1e730 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1e740 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1e750 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1e760 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1e770 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1e780 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1e790 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1e7a0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1e7b0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1e7c0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1e7d0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1e7e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1e7f0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1e800 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1e810 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1e820 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1e830 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1e840 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1e850 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1e860 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1e870 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1e880 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1e890 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1e8a0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1e8b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1e8c0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1e8d0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1e8e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1e8f0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1e900 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1e910 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1e920 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1e930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e940 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1e950 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1e960 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1e970 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1e980 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1e990 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1e9a0 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1e9b0 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1e9c0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1e9d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1e9e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1e9f0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1ea00 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1ea10 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1ea20 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1ea30 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1ea40 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1ea50 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1ea60 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1ea70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1ea80 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1ea90 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1eaa0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1eab0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1eac0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1ead0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1eae0 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1eaf0 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1eb00 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1eb10 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1eb20 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1eb30 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1eb40 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1eb50 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1eb60 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1eb70 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1eb80 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1eb90 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1eba0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1ebb0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1ebc0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1ebd0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1ebe0 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1ebf0 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1ec00 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1ec10 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1ec20 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1ec30 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1ec40 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1ec50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1ec60 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1ec70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1ec80 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1ec90 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1eca0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1ecb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ecc0 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1ecd0 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1ece0 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1ecf0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ed00 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1ed10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1ed20 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1ed30 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1ed40 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1ed50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1ed60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1ed70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1ed80 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1ed90 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1eda0 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1edb0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1edc0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1edd0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1ede0 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1edf0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ee00 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1ee10 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1ee20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1ee30 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1ee40 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1ee50 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1ee60 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1ee70 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1ee80 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1ee90 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1eea0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1eeb0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1eec0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1eed0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1eee0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1eef0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1ef00 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1ef10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ef20 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1ef30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1ef40 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1ef50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1ef60 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1ef70 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1ef80 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1ef90 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1efa0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1efb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1efc0 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
1efd0 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
1efe0 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
1eff0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f000 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
1f010 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
1f020 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
1f030 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
1f040 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
1f050 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
1f060 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
1f070 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
1f080 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
1f090 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1f0a0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1f0b0 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
1f0c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
1f0d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f0e0 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
1f0f0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1f100 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
1f110 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
1f120 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
1f130 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
1f140 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1f150 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
1f160 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
1f170 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
1f180 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
1f190 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
1f1a0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
1f1b0 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1f1c0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1f1d0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1f1e0 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
1f1f0 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
1f200 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
1f210 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
1f220 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
1f230 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
1f240 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
1f250 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
1f260 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f270 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
1f280 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
1f290 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
1f2a0 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
1f2b0 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
1f2c0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
1f2d0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
1f2e0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1f2f0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1f300 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
1f310 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1f320 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1f330 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1f340 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
1f350 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1f360 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1f370 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1f380 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1f390 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1f3a0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1f3b0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1f3c0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1f3d0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1f3e0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1f3f0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1f400 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1f410 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1f420 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1f430 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1f440 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1f450 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1f460 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1f470 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1f480 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1f490 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1f4a0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1f4b0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1f4c0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1f4d0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1f4e0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1f4f0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1f500 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1f510 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1f520 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1f530 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1f540 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1f550 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1f560 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1f570 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1f580 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1f590 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1f5a0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1f5b0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1f5c0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1f5d0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1f5e0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1f5f0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1f600 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1f610 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1f620 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1f630 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1f640 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1f650 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1f660 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1f670 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1f680 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1f690 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1f6a0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1f6b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f6c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1f6d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1f6e0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1f6f0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1f700 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1f710 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1f720 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1f730 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1f740 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f750 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1f760 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1f770 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1f780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1f790 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1f7a0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1f7b0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1f7c0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1f7d0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1f7e0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1f7f0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1f800 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1f810 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1f820 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1f830 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1f840 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
1f850 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
1f860 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1f870 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1f880 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1f890 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1f8a0 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1f8b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1f8c0 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
1f8d0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
1f8e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1f8f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1f900 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1f910 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1f920 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1f930 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1f940 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1f950 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1f960 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1f970 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1f980 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1f990 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1f9a0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1f9b0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1f9c0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1f9d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1f9e0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1f9f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1fa00 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1fa10 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1fa20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1fa30 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1fa40 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1fa50 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1fa60 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1fa70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1fa80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1fa90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1faa0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1fab0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1fac0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fad0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1fae0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1faf0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1fb00 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1fb10 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1fb20 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1fb30 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1fb40 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fb50 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1fb60 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1fb70 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1fb80 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1fb90 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1fba0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1fbb0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1fbc0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1fbd0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1fbe0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1fbf0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1fc00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1fc10 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1fc20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1fc30 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1fc40 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1fc50 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1fc60 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1fc70 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1fc80 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1fc90 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1fca0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fcb0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1fcc0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1fcd0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1fce0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fcf0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1fd00 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1fd10 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1fd20 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1fd30 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1fd40 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1fd50 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1fd60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1fd70 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1fd80 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1fd90 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1fda0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1fdb0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1fdc0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1fdd0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1fde0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1fdf0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1fe00 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1fe10 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1fe20 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1fe30 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1fe40 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1fe50 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1fe60 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1fe70 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1fe80 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1fe90 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1fea0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1feb0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1fec0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1fed0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1fee0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1fef0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1ff00 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1ff10 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1ff20 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1ff30 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1ff40 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1ff50 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1ff60 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1ff70 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
1ff80 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
1ff90 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1ffa0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
1ffb0 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
1ffc0 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
1ffd0 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
1ffe0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
1fff0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
20000 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
20010 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
20020 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
20030 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
20040 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
20050 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
20060 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
20070 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
20080 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
20090 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
200a0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
200b0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
200c0 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
200d0 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
200e0 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
200f0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
20100 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
20110 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
20120 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
20130 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
20140 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
20150 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
20160 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
20170 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
20180 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
20190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
201a0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
201b0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
201c0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
201d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
201e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
201f0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
20200 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
20210 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
20220 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
20230 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
20240 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
20250 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
20260 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20270 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20280 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
20290 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
202a0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
202b0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
202c0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
202d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
202e0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
202f0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
20300 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
20310 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
20320 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
20330 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
20340 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
20350 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
20360 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
20370 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
20380 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
20390 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
203a0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
203b0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
203c0 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
203d0 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
203e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
203f0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
20400 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
20410 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
20420 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
20430 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
20440 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
20450 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
20460 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
20470 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
20480 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
20490 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
204a0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
204b0 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
204c0 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
204d0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
204e0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
204f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20500 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
20510 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
20520 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
20530 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
20540 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
20550 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
20560 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20570 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
20580 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
20590 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
205a0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
205b0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
205c0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
205d0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
205e0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
205f0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
20600 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
20610 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
20620 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
20630 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20640 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
20650 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20660 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20670 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
20680 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
20690 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
206a0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
206b0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
206c0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
206d0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
206e0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
206f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20700 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
20710 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
20720 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
20730 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
20740 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
20750 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
20760 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
20770 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
20780 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
20790 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
207a0 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
207b0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
207c0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
207d0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
207e0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
207f0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
20800 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
20810 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
20820 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20830 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
20840 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
20850 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
20860 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
20870 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
20880 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20890 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
208a0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
208b0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
208c0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
208d0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
208e0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
208f0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
20900 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
20910 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
20920 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
20930 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
20940 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
20950 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
20960 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
20970 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
20980 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
20990 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
209a0 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
209b0 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
209c0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
209d0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
209e0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
209f0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
20a00 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
20a10 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
20a20 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
20a30 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
20a40 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
20a50 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
20a60 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
20a70 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
20a80 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
20a90 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
20aa0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
20ab0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
20ac0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
20ad0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
20ae0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
20af0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
20b00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20b10 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
20b20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
20b30 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
20b40 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
20b50 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
20b60 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20b70 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
20b80 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
20b90 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
20ba0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
20bb0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
20bc0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
20bd0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
20be0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
20bf0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
20c00 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
20c10 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
20c20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
20c30 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
20c40 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
20c50 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
20c60 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
20c70 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
20c80 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
20c90 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
20ca0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
20cb0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
20cc0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
20cd0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
20ce0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
20cf0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
20d00 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
20d10 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
20d20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
20d30 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
20d40 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
20d50 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
20d60 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
20d70 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
20d80 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
20d90 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
20da0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
20db0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
20dc0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
20dd0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
20de0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
20df0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
20e00 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
20e10 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
20e20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
20e30 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20e40 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
20e50 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
20e60 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
20e70 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
20e80 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
20e90 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
20ea0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
20eb0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
20ec0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
20ed0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
20ee0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
20ef0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
20f00 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
20f10 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
20f20 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
20f30 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
20f40 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
20f50 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
20f60 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
20f70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
20f80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
20f90 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
20fa0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
20fb0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
20fc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20fd0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
20fe0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20ff0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
21000 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
21010 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
21020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
21030 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
21040 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
21050 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
21060 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
21070 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
21080 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
21090 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
210a0 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
210b0 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
210c0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
210d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
210e0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
210f0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
21100 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
21110 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
21120 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
21130 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
21140 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
21150 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
21160 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21170 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
21180 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
21190 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
211a0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
211b0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
211c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
211d0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
211e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
211f0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
21200 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
21210 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
21220 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
21230 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
21240 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
21250 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
21260 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
21270 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
21280 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
21290 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
212a0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
212b0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
212c0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
212d0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
212e0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
212f0 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
21300 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
21310 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
21320 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
21330 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
21340 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
21350 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
21360 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
21370 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
21380 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
21390 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
213a0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
213b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
213c0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
213d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
213e0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
213f0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
21400 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
21410 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
21420 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
21430 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
21440 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
21450 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
21460 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
21470 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
21480 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
21490 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
214a0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
214b0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
214c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
214d0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
214e0 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
214f0 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
21500 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
21510 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
21520 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
21530 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
21540 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
21550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21560 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
21570 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
21580 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
21590 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
215a0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
215b0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
215c0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
215d0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
215e0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
215f0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
21600 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
21610 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
21620 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
21630 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
21640 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
21650 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
21660 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
21670 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
21680 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
21690 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
216a0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
216b0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
216c0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
216d0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
216e0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
216f0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
21700 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
21710 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
21720 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
21730 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
21740 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
21750 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
21760 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
21770 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
21780 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
21790 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
217a0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
217b0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
217c0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
217d0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
217e0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
217f0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
21800 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
21810 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
21820 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
21830 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
21840 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
21850 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
21860 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
21870 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
21880 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21890 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
218a0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
218b0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
218c0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
218d0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
218e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
218f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21900 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
21910 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
21920 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
21930 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
21940 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
21950 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
21960 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
21970 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
21980 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
21990 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
219a0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
219b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
219c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
219d0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
219e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
219f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
21a00 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21a10 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21a20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
21a30 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21a40 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21a50 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21a60 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
21a70 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21a80 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21a90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21aa0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21ab0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
21ac0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21ad0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
21ae0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21af0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21b00 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
21b10 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21b20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21b30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21b40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21b50 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
21b60 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21b70 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21b80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21b90 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21ba0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
21bb0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
21bc0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21bd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21be0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
21bf0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
21c00 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
21c10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21c20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21c30 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
21c40 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
21c50 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
21c60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21c80 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
21c90 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
21ca0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21cb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21cd0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
21ce0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
21cf0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21d00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21d20 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
21d30 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
21d40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21d50 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21d60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21d70 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
21d80 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
21d90 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
21da0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21db0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21dc0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
21dd0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
21de0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21df0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21e00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21e10 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
21e20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
21e30 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21e40 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21e50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21e60 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
21e70 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
21e80 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
21e90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21ea0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21eb0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
21ec0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
21ed0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
21ee0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21ef0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
21f00 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
21f10 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
21f20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21f30 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21f40 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
21f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
21f60 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21f70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21f80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21f90 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
21fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
21fb0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
21fc0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
21fd0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
21fe0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
21ff0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
22000 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22010 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
22020 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22030 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
22040 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
22050 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
22060 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22070 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22080 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
22090 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
220a0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
220b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
220c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
220d0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
220e0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
220f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22100 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
22110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22120 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
22130 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
22140 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
22150 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22160 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22170 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
22180 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
22190 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
221a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
221b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
221c0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
221d0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
221e0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
221f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22210 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
22220 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
22230 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
22240 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22250 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
22260 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
22270 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
22280 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22290 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
222a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
222b0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
222c0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
222d0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
222e0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
222f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22300 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
22310 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
22320 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
22330 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
22340 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
22350 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
22360 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
22370 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
22380 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
22390 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
223a0 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
223b0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
223c0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
223d0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
223e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
223f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22400 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
22410 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
22420 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
22430 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
22440 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
22450 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22460 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
22470 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
22480 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
22490 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
224a0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
224b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
224c0 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
224d0 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
224e0 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
224f0 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
22500 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
22510 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
22520 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
22530 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
22540 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22550 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
22560 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
22570 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
22580 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
22590 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
225a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
225b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
225c0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
225d0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
225e0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
225f0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
22600 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
22610 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
22620 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
22630 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
22640 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
22650 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22660 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
22670 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
22680 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
22690 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
226a0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
226b0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
226c0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
226d0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
226e0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
226f0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
22700 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
22710 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
22720 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
22730 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
22740 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
22750 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
22760 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
22770 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
22780 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
22790 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
227a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
227b0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
227c0 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
227d0 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
227e0 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
227f0 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
22800 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
22810 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
22820 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22830 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
22840 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22850 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
22860 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
22870 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
22880 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
22890 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
228a0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
228b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
228c0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
228d0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
228e0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
228f0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
22900 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
22910 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
22920 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
22930 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
22940 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
22950 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
22960 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
22970 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
22980 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
22990 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
229a0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
229b0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
229c0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
229d0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
229e0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
229f0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
22a00 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
22a10 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
22a20 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
22a30 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
22a40 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
22a50 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
22a60 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
22a70 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
22a80 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
22a90 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
22aa0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
22ab0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
22ac0 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
22ad0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
22ae0 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
22af0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
22b00 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
22b10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
22b20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
22b30 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
22b40 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
22b50 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
22b60 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
22b70 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
22b80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
22b90 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
22ba0 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
22bb0 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
22bc0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
22bd0 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
22be0 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
22bf0 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
22c00 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
22c10 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
22c20 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
22c30 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
22c40 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
22c50 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
22c60 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
22c70 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
22c80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
22c90 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
22ca0 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
22cb0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
22cc0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
22cd0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
22ce0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
22cf0 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
22d00 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
22d10 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
22d20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
22d30 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
22d40 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
22d50 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
22d60 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
22d70 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
22d80 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
22d90 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
22da0 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
22db0 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
22dc0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
22dd0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
22de0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
22df0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
22e00 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
22e10 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
22e20 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
22e30 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
22e40 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
22e50 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
22e60 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
22e70 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
22e80 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
22e90 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
22ea0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
22eb0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
22ec0 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
22ed0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
22ee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22ef0 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
22f00 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
22f10 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
22f20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
22f30 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
22f40 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
22f50 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
22f60 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
22f70 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
22f80 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
22f90 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
22fa0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
22fb0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
22fc0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
22fd0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22fe0 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
22ff0 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
23000 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
23010 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
23020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23030 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
23040 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
23050 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
23060 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
23070 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
23080 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
23090 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
230a0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
230b0 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
230c0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
230d0 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
230e0 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
230f0 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
23100 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
23110 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
23120 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
23130 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
23140 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
23150 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
23160 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
23170 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
23180 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
23190 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
231a0 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
231b0 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
231c0 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
231d0 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
231e0 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
231f0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
23200 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
23210 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
23220 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
23230 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
23240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23250 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
23260 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
23270 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
23280 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
23290 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
232a0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
232b0 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
232c0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
232d0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
232e0 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
232f0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
23300 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
23310 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
23320 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
23330 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
23340 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
23350 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
23360 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
23370 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
23380 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
23390 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
233a0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
233b0 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
233c0 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
233d0 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
233e0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
233f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23400 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23410 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
23420 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
23430 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
23440 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
23450 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
23460 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
23470 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
23480 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
23490 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
234a0 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
234b0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
234c0 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
234d0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
234e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
234f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23500 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
23510 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
23520 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
23530 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
23540 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23550 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
23560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23570 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
23580 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
23590 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
235a0 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
235b0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
235c0 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
235d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
235e0 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
235f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
23600 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
23610 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
23620 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
23630 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
23640 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
23650 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
23660 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
23670 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
23680 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
23690 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
236a0 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
236b0 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
236c0 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
236d0 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
236e0 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
236f0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
23700 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
23710 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
23720 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
23730 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
23740 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
23750 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
23760 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
23770 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
23780 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
23790 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
237a0 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
237b0 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
237c0 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
237d0 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
237e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
237f0 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
23800 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
23810 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
23820 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
23830 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
23840 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
23850 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
23860 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
23870 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
23880 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
23890 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
238a0 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
238b0 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
238c0 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
238d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
238e0 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
238f0 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
23900 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
23910 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
23920 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
23930 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
23940 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
23950 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
23960 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
23970 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
23980 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
23990 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
239a0 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
239b0 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
239c0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
239d0 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
239e0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
239f0 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
23a00 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
23a10 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
23a20 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
23a30 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
23a40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23a50 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
23a60 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
23a70 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
23a80 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
23a90 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
23aa0 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
23ab0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
23ac0 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
23ad0 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
23ae0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23af0 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
23b00 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
23b10 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
23b20 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
23b30 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
23b40 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
23b50 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
23b60 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
23b70 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
23b80 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
23b90 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
23ba0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
23bb0 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
23bc0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
23bd0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
23be0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
23bf0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
23c00 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
23c10 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
23c20 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
23c30 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
23c40 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
23c50 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
23c60 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
23c70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23c80 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
23c90 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
23ca0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
23cb0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
23cc0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
23cd0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
23ce0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
23cf0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
23d00 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
23d10 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
23d20 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
23d30 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
23d40 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
23d50 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
23d60 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
23d70 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
23d80 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
23d90 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
23da0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
23db0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
23dc0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
23dd0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
23de0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
23df0 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
23e00 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
23e10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
23e20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
23e30 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
23e40 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
23e50 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
23e60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23e70 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
23e80 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23e90 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
23ea0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
23eb0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
23ec0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
23ed0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
23ee0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
23ef0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
23f00 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
23f10 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
23f20 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
23f30 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
23f40 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
23f50 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
23f60 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
23f70 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
23f80 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
23f90 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
23fa0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
23fb0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
23fc0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
23fd0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
23fe0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
23ff0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24000 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
24010 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
24020 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
24030 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
24040 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
24050 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
24060 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
24070 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
24080 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24090 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
240a0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
240b0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
240c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
240d0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
240e0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
240f0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
24100 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
24110 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
24120 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
24130 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
24140 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
24150 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
24160 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
24170 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
24180 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
24190 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
241a0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
241b0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
241c0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
241d0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
241e0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
241f0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
24200 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
24210 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
24220 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
24230 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
24240 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
24250 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
24260 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
24270 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
24280 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
24290 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
242a0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
242b0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
242c0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
242d0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
242e0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
242f0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
24300 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
24310 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
24320 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24330 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
24340 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
24350 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
24360 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
24370 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
24380 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
24390 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
243a0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
243b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
243c0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
243d0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
243e0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
243f0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
24400 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
24410 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
24420 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
24430 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
24440 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
24450 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
24460 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
24470 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
24480 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
24490 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
244a0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
244b0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
244c0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
244d0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
244e0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
244f0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
24500 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
24510 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
24520 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
24530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24540 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
24550 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
24560 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
24570 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
24580 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
24590 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
245a0 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
245b0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
245c0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
245d0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
245e0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
245f0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
24600 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
24610 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
24620 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
24630 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
24640 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
24650 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
24660 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
24670 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
24680 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
24690 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
246a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
246b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
246c0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
246d0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
246e0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
246f0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
24700 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
24710 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
24720 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
24730 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
24740 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
24750 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
24760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24770 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
24780 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
24790 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
247a0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
247b0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
247c0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
247d0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
247e0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
247f0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
24800 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
24810 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
24820 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
24830 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
24840 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
24850 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
24860 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
24870 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
24880 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
24890 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
248a0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
248b0 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
248c0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
248d0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
248e0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
248f0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
24900 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
24910 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
24920 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24930 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
24940 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
24950 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
24960 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
24970 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
24980 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
24990 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
249a0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
249b0 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
249c0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
249d0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
249e0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
249f0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
24a00 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
24a10 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
24a20 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
24a30 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
24a40 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
24a50 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
24a60 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24a70 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
24a80 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
24a90 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
24aa0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
24ab0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
24ac0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
24ad0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
24ae0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
24af0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
24b00 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
24b10 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
24b20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
24b30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
24b40 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
24b50 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
24b60 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
24b70 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
24b80 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
24b90 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
24ba0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
24bb0 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
24bc0 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
24bd0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
24be0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
24bf0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
24c00 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
24c10 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
24c20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24c30 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
24c40 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
24c50 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
24c60 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
24c70 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
24c80 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
24c90 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
24ca0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
24cb0 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
24cc0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
24cd0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
24ce0 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
24cf0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24d00 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
24d10 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
24d20 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
24d30 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
24d40 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
24d50 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
24d60 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
24d70 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
24d80 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
24d90 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
24da0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
24db0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24dc0 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
24dd0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
24de0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
24df0 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
24e00 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
24e10 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
24e20 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
24e30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
24e40 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
24e50 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
24e60 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
24e70 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
24e80 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24e90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24ea0 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
24eb0 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
24ec0 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
24ed0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
24ee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
24ef0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24f00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24f10 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
24f20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
24f30 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
24f40 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
24f50 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
24f60 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
24f70 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
24f80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
24f90 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
24fa0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
24fb0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
24fc0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
24fd0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
24fe0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
24ff0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
25000 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25010 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
25020 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
25030 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
25040 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
25050 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
25060 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
25070 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
25080 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
25090 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
250a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
250b0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
250c0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
250d0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
250e0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
250f0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
25100 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
25110 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
25120 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
25130 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
25140 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
25150 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
25160 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
25170 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
25180 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
25190 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
251a0 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
251b0 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
251c0 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
251d0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
251e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
251f0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
25200 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
25210 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
25220 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
25230 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
25240 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
25250 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
25260 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
25270 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
25280 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
25290 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
252a0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
252b0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
252c0 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
252d0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
252e0 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
252f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
25300 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
25310 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
25320 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
25330 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
25340 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
25350 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
25360 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
25370 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
25380 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
25390 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
253a0 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
253b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
253c0 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
253d0 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
253e0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
253f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25400 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
25410 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
25420 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
25430 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
25440 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
25450 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
25460 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
25470 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
25480 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
25490 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
254a0 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
254b0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
254c0 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
254d0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
254e0 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
254f0 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
25500 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
25510 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
25520 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
25530 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
25540 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
25550 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
25560 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
25570 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
25580 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
25590 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
255a0 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
255b0 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
255c0 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
255d0 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
255e0 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
255f0 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
25600 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
25610 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
25620 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
25630 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
25640 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
25650 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
25660 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
25670 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
25680 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
25690 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
256a0 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
256b0 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
256c0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
256d0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
256e0 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
256f0 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
25700 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
25710 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
25720 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
25730 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
25740 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
25750 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
25760 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
25770 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
25780 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
25790 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
257a0 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
257b0 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
257c0 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
257d0 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
257e0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
257f0 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
25800 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
25810 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
25820 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
25830 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
25840 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
25850 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
25860 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
25870 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
25880 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
25890 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
258a0 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
258b0 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
258c0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
258d0 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
258e0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
258f0 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
25900 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
25910 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
25920 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
25930 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
25940 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
25950 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
25960 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
25970 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
25980 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
25990 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
259a0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
259b0 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
259c0 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
259d0 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
259e0 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
259f0 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
25a00 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
25a10 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
25a20 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
25a30 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
25a40 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
25a50 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
25a60 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
25a70 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
25a80 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
25a90 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
25aa0 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
25ab0 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
25ac0 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
25ad0 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
25ae0 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
25af0 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
25b00 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
25b10 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
25b20 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
25b30 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
25b40 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
25b50 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
25b60 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
25b70 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
25b80 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
25b90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25ba0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25bb0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
25bc0 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
25bd0 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
25be0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
25bf0 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
25c00 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
25c10 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
25c20 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
25c30 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
25c40 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
25c50 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
25c60 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
25c70 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
25c80 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
25c90 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
25ca0 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
25cb0 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
25cc0 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
25cd0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
25ce0 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
25cf0 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
25d00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
25d10 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25d20 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
25d30 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
25d40 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
25d50 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
25d60 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
25d70 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
25d80 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
25d90 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
25da0 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
25db0 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
25dc0 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
25dd0 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
25de0 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
25df0 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
25e00 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
25e10 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
25e20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25e30 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
25e40 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
25e50 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
25e60 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
25e70 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
25e80 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
25e90 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
25ea0 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
25eb0 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
25ec0 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
25ed0 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
25ee0 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
25ef0 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
25f00 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
25f10 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
25f20 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
25f30 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
25f40 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
25f50 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
25f60 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
25f70 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25f80 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
25f90 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
25fa0 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
25fb0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
25fc0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
25fd0 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
25fe0 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
25ff0 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
26000 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
26010 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
26020 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
26030 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
26040 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
26050 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
26060 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
26070 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
26080 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
26090 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
260a0 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
260b0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
260c0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
260d0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
260e0 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
260f0 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
26100 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
26110 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
26120 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
26130 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
26140 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
26150 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
26160 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
26170 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
26180 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
26190 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
261a0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
261b0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
261c0 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
261d0 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
261e0 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
261f0 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
26200 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
26210 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
26220 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
26230 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
26240 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
26250 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
26260 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
26270 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
26280 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
26290 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
262a0 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
262b0 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
262c0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
262d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
262e0 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
262f0 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
26300 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
26310 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
26320 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
26330 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
26340 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
26350 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
26360 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
26370 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
26380 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
26390 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
263a0 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
263b0 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
263c0 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
263d0 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
263e0 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
263f0 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
26400 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
26410 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
26420 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
26430 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
26440 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
26450 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
26460 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
26470 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
26480 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
26490 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
264a0 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
264b0 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
264c0 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
264d0 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
264e0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
264f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
26500 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
26510 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
26520 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
26530 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
26540 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
26550 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
26560 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
26570 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
26580 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
26590 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
265a0 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
265b0 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
265c0 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
265d0 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
265e0 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
265f0 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
26600 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
26610 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
26620 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
26630 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
26640 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
26650 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
26660 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
26670 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
26680 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
26690 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
266a0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
266b0 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
266c0 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
266d0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
266e0 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
266f0 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
26700 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
26710 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
26720 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
26730 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
26740 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
26750 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
26760 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
26770 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
26780 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
26790 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
267a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
267b0 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
267c0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
267d0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
267e0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
267f0 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
26800 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
26810 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
26820 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
26830 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
26840 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
26850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
26860 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
26870 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
26880 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
26890 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
268a0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
268b0 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
268c0 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
268d0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
268e0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
268f0 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
26900 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26910 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
26920 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
26930 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26940 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
26950 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
26960 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
26970 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
26980 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
26990 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
269a0 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
269b0 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
269c0 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
269d0 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
269e0 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
269f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
26a00 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
26a10 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
26a20 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
26a30 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
26a40 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
26a50 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
26a60 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
26a70 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
26a80 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
26a90 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
26aa0 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
26ab0 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
26ac0 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
26ad0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
26ae0 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
26af0 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
26b00 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
26b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
26b20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
26b30 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
26b40 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
26b50 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
26b60 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
26b70 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
26b80 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
26b90 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
26ba0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
26bb0 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
26bc0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
26bd0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
26be0 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
26bf0 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
26c00 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
26c10 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
26c20 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
26c30 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
26c40 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
26c50 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
26c60 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
26c70 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
26c80 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
26c90 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
26ca0 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
26cb0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
26cc0 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
26cd0 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
26ce0 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
26cf0 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
26d00 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
26d10 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
26d20 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
26d30 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
26d40 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
26d50 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
26d60 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
26d70 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
26d80 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
26d90 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
26da0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
26db0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
26dc0 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
26dd0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
26de0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
26df0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26e00 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
26e10 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
26e20 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
26e30 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
26e40 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
26e50 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
26e60 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
26e70 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
26e80 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
26e90 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
26ea0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
26eb0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
26ec0 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
26ed0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
26ee0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
26ef0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
26f00 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
26f10 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
26f20 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
26f30 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
26f40 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
26f50 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
26f60 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
26f70 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
26f80 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
26f90 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
26fa0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
26fb0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
26fc0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
26fd0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
26fe0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
26ff0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
27000 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
27010 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
27020 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
27030 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
27040 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
27050 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
27060 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
27070 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
27080 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
27090 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
270a0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
270b0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
270c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
270d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
270e0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
270f0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
27100 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
27110 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
27120 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
27130 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
27140 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
27150 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
27160 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27170 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
27180 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
27190 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
271a0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
271b0 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
271c0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
271d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
271e0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
271f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27200 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
27210 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
27220 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27230 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
27240 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
27250 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
27260 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
27270 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
27280 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
27290 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
272a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
272b0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
272c0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
272d0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
272e0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
272f0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
27300 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27310 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
27320 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
27330 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
27340 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
27350 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
27360 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
27370 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
27380 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
27390 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
273a0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
273b0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
273c0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
273d0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
273e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
273f0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
27400 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
27410 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
27420 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
27430 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
27440 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
27450 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
27460 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
27470 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
27480 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
27490 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
274a0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
274b0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
274c0 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
274d0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
274e0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
274f0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
27500 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
27510 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
27520 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
27530 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
27540 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
27550 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
27560 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
27570 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
27580 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
27590 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
275a0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
275b0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
275c0 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
275d0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
275e0 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
275f0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
27600 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
27610 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
27620 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
27630 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
27640 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
27650 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
27660 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
27670 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
27680 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
27690 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
276a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
276b0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
276c0 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
276d0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
276e0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
276f0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
27700 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
27710 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
27720 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27730 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
27740 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
27750 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
27760 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
27770 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
27780 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
27790 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
277a0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
277b0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
277c0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
277d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
277e0 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
277f0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
27800 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
27810 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
27820 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
27830 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
27840 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
27850 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
27860 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
27870 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27880 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27890 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
278a0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
278b0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
278c0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
278d0 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
278e0 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
278f0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
27900 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
27910 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
27920 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
27930 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
27940 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
27950 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
27960 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
27970 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
27980 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
27990 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
279a0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
279b0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
279c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
279d0 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
279e0 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
279f0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
27a00 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
27a10 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
27a20 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
27a30 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
27a40 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
27a50 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
27a60 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
27a70 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
27a80 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
27a90 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
27aa0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
27ab0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
27ac0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
27ad0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
27ae0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
27af0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
27b00 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
27b10 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
27b20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
27b30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
27b40 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
27b50 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
27b60 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
27b70 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
27b80 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
27b90 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
27ba0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
27bb0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
27bc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
27bd0 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
27be0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
27bf0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
27c00 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
27c10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
27c20 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
27c30 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
27c40 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
27c50 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
27c60 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
27c70 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
27c80 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
27c90 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
27ca0 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
27cb0 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
27cc0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
27cd0 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
27ce0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
27cf0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
27d00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
27d10 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  3.**.** ^If the 
27d20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c 69  most recent sqli
27d30 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
27d40 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
27d50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
27d60 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65  nection] D faile
27d70 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  d, then the sqli
27d80 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 69  te3_errcode(D) i
27d90 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
27da0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
27db0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
27dc0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
27dd0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 74  t code] for that
27de0 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a  .** API call..**
27df0 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
27e00 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 73  ent API call was
27e10 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20   successful,.** 
27e20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
27e30 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
27e40 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
27e50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54  undefined..** ^T
27e60 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
27e70 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
27e80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
27e90 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
27ea0 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
27eb0 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
27ec0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
27ed0 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
27ee0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
27ef0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
27f00 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
27f10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
27f20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
27f30 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
27f40 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
27f50 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
27f60 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
27f70 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
27f80 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
27f90 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
27fa0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
27fb0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
27fc0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
27fd0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
27fe0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
27ff0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
28000 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
28010 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
28020 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
28030 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
28040 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
28050 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
28060 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
28070 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
28080 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
28090 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
280a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
280b0 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
280c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
280d0 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
280e0 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
280f0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
28100 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
28110 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
28120 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
28130 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
28140 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
28150 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
28160 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
28170 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
28180 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
28190 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
281a0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
281b0 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
281c0 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
281d0 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
281e0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
281f0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
28200 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
28210 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
28220 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
28230 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
28240 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
28250 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
28260 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
28270 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
28280 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
28290 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
282a0 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
282b0 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
282c0 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
282d0 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
282e0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
282f0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
28300 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
28310 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
28320 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
28330 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
28340 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
28350 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
28360 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
28370 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
28380 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
28390 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
283a0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
283b0 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
283c0 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
283d0 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
283e0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
283f0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
28400 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
28410 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
28420 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
28430 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
28440 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
28450 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
28460 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
28470 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
28480 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
28490 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
284a0 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
284b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
284c0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
284d0 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
284e0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
284f0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
28500 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28510 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
28520 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
28530 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
28540 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
28550 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28560 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
28570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28580 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
28590 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
285a0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
285b0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
285c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
285d0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
285e0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
285f0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
28600 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
28610 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
28620 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
28630 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
28640 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
28650 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
28660 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
28670 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
28680 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
28690 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
286a0 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
286b0 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
286c0 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
286d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
286e0 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
286f0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
28700 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
28710 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
28720 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
28730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28740 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
28750 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
28760 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
28770 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
28780 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
28790 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
287a0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
287b0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
287c0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
287d0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
287e0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
287f0 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
28800 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
28810 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
28820 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
28830 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
28840 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28850 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
28860 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
28870 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
28880 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28890 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
288a0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
288b0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
288c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
288d0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
288e0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
288f0 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
28900 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
28910 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
28920 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
28930 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
28940 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
28950 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28960 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
28970 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
28980 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
28990 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
289a0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
289b0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
289c0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
289d0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
289e0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
289f0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
28a00 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
28a10 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
28a20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
28a30 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
28a40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28a50 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
28a60 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
28a70 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
28a80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
28a90 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
28aa0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
28ab0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
28ac0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
28ad0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
28ae0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
28af0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28b00 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
28b10 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
28b20 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
28b30 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
28b40 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
28b50 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
28b60 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
28b70 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
28b80 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
28b90 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
28ba0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
28bb0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
28bc0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
28bd0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
28be0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
28bf0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
28c00 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
28c10 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
28c20 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
28c30 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
28c40 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
28c50 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
28c60 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
28c70 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
28c80 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
28c90 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
28ca0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
28cb0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
28cc0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
28cd0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
28ce0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
28cf0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
28d00 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
28d10 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
28d20 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
28d30 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
28d40 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
28d50 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
28d60 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
28d70 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
28d80 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
28d90 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
28da0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
28db0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
28dc0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
28dd0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
28de0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
28df0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
28e00 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
28e10 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
28e20 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
28e30 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
28e40 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
28e50 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
28e60 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
28e70 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
28e80 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
28e90 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
28ea0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
28eb0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
28ec0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
28ed0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
28ee0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
28ef0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
28f00 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
28f10 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
28f20 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
28f30 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
28f40 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
28f50 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
28f60 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
28f70 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
28f80 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
28f90 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
28fa0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
28fb0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
28fc0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
28fd0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
28fe0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
28ff0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
29000 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
29010 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
29020 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
29030 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
29040 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
29050 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
29060 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
29070 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
29080 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
29090 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
290a0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
290b0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
290c0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
290d0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
290e0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
290f0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
29100 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
29110 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
29120 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
29130 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
29140 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
29150 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
29160 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
29170 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
29180 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
29190 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
291a0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
291b0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
291c0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
291d0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
291e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
291f0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
29200 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
29210 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
29220 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
29230 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29240 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
29250 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
29260 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
29270 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
29280 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
29290 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
292a0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
292b0 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
292c0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
292d0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
292e0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
292f0 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
29300 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
29310 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
29320 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
29330 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
29340 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
29350 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
29360 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
29370 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
29380 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
29390 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
293a0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
293b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
293c0 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
293d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
293e0 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
293f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29400 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
29410 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
29420 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
29430 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29440 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
29450 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
29460 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
29470 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
29480 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
29490 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
294a0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
294b0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
294c0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
294d0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
294e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
294f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29500 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
29510 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
29520 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
29530 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29540 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
29550 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
29560 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
29570 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29580 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
29590 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
295a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
295b0 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
295c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
295d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
295e0 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
295f0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
29600 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
29610 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
29620 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
29630 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
29640 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
29650 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29660 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
29670 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
29680 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
29690 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
296a0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
296b0 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c  tement.  If [sql
296c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
296d0 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75  )] or.** the equ
296e0 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74 6f  ivalent tries to
296f0 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65 20   allocate space 
29700 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  for more than th
29710 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a  is many opcodes.
29720 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 70  ** in a single p
29730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29740 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d  t, an SQLITE_NOM
29750 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  EM error is retu
29760 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
29770 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29780 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
29790 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
297a0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
297b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
297c0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
297d0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
297e0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
297f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29800 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
29810 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29820 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
29830 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
29840 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
29850 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
29860 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
29870 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
29880 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
29890 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
298a0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
298b0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
298c0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
298d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
298e0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
298f0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
29900 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
29910 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
29920 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
29930 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29940 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29950 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
29960 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29970 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
29980 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29990 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
299a0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
299b0 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
299c0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
299d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
299e0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
299f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
29a00 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
29a10 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29a20 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
29a30 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
29a40 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
29a50 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29a60 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
29a70 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
29a80 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
29a90 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
29aa0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29ab0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
29ac0 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
29ad0 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
29ae0 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
29af0 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
29b00 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
29b10 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
29b20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
29b30 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29b40 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
29b50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
29b60 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
29b70 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
29b80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29b90 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
29ba0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
29bb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29bc0 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
29bd0 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
29be0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29bf0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29c00 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
29c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29c20 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
29c30 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
29c40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29c50 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
29c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
29c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29c80 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
29c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
29ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29cb0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
29cc0 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
29cd0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
29ce0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
29cf0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
29d00 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
29d10 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
29d20 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
29d30 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
29d40 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
29d50 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
29d60 20 20 31 31 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50    11.../*.** CAP
29d70 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
29d80 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
29d90 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
29da0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
29db0 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
29dc0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
29dd0 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
29de0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
29df0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
29e00 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
29e10 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
29e20 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
29e30 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
29e40 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
29e50 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
29e60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
29e70 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
29e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29e90 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
29ea0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
29eb0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
29ec0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
29ed0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
29ee0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
29ef0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
29f00 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
29f10 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
29f20 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
29f30 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
29f40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
29f50 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
29f60 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
29f70 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
29f80 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
29f90 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
29fa0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
29fb0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
29fc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
29fd0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
29fe0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
29ff0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
2a000 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2a010 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
2a020 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
2a030 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
2a040 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
2a050 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
2a060 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
2a070 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
2a080 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
2a090 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
2a0a0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
2a0b0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2a0c0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
2a0d0 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
2a0e0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
2a0f0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2a100 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
2a110 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
2a120 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
2a130 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
2a140 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
2a150 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
2a160 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
2a170 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
2a180 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
2a190 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
2a1a0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
2a1b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2a1c0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
2a1d0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
2a1e0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
2a1f0 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
2a200 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
2a210 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
2a220 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
2a230 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
2a240 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
2a250 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
2a260 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
2a270 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
2a280 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
2a290 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
2a2a0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
2a2b0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
2a2c0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
2a2d0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
2a2e0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
2a2f0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
2a300 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
2a310 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
2a320 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
2a330 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
2a340 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
2a350 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2a360 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
2a370 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
2a380 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
2a390 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
2a3a0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
2a3b0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
2a3c0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
2a3d0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
2a3e0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
2a3f0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
2a400 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
2a410 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
2a420 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
2a430 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
2a440 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
2a450 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
2a460 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
2a470 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
2a480 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
2a490 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
2a4a0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
2a4b0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
2a4c0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
2a4d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a4e0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
2a4f0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2a500 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
2a510 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
2a520 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2a530 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2a540 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a550 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a560 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
2a570 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
2a580 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
2a590 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
2a5a0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
2a5b0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
2a5c0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
2a5d0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2a5e0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
2a5f0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
2a600 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
2a610 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
2a620 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2a630 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
2a640 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
2a650 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2a660 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
2a670 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2a680 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
2a690 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
2a6a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2a6b0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
2a6c0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
2a6d0 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
2a6e0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
2a6f0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
2a700 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2a710 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
2a720 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
2a730 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
2a740 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
2a750 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
2a760 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a770 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2a780 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
2a790 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2a7a0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
2a7b0 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
2a7c0 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
2a7d0 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
2a7e0 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
2a7f0 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
2a800 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
2a810 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
2a820 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
2a830 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2a840 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
2a850 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
2a860 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
2a870 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
2a880 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
2a890 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
2a8a0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2a8b0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
2a8c0 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
2a8d0 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
2a8e0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
2a8f0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
2a900 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
2a910 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
2a920 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
2a930 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
2a940 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
2a950 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
2a960 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2a970 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2a980 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2a990 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
2a9a0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
2a9b0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
2a9c0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
2a9d0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
2a9e0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
2a9f0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
2aa00 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
2aa10 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2aa20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
2aa30 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
2aa40 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
2aa50 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2aa60 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
2aa70 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
2aa80 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
2aa90 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
2aaa0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
2aab0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
2aac0 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
2aad0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2aae0 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
2aaf0 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
2ab00 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
2ab10 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
2ab20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2ab30 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
2ab40 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
2ab50 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2ab60 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
2ab70 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
2ab80 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
2ab90 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
2aba0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
2abb0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
2abc0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
2abd0 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
2abe0 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
2abf0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2ac00 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2ac10 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
2ac20 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2ac30 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
2ac40 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
2ac50 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
2ac60 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
2ac70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2ac80 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
2ac90 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
2aca0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
2acb0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
2acc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2acd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2ace0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2acf0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2ad00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2ad10 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2ad20 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2ad30 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2ad40 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ad50 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ad60 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2ad70 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2ad80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2ad90 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ada0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2adb0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2adc0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2add0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2ade0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2adf0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2ae00 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2ae10 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2ae20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ae30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ae40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ae50 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2ae60 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ae70 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2ae80 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2ae90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2aea0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2aeb0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2aec0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2aed0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2aee0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2aef0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2af00 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2af10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2af20 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2af30 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2af40 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2af50 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
2af60 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2af70 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2af80 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2af90 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2afa0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2afb0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2afc0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2afd0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2afe0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2aff0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2b000 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2b010 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2b020 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2b030 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2b040 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2b050 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2b060 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2b070 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2b080 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2b090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b0a0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2b0b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2b0c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2b0d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2b0e0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2b0f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2b100 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2b110 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2b120 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2b130 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2b140 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2b150 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2b160 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2b170 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2b180 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2b190 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2b1a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2b1b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2b1c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2b1d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2b1e0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2b1f0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2b200 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b210 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2b220 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2b230 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b240 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2b250 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46   copy of the UTF
2b260 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  -8.** SQL text u
2b270 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70  sed to create [p
2b280 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b290 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a  t] P if P was.**
2b2a0 20 63 72 65 61 74 65 64 20 62 79 20 65 69 74 68   created by eith
2b2b0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2b2c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2b2d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b2e0 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  v2()]..** ^The s
2b2f0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b300 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2b310 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2b320 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a  er to a UTF-8.**
2b330 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2b340 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  ng the SQL text 
2b350 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2b360 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20  ement P with.** 
2b370 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
2b380 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a  s] expanded..**.
2b390 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2b3a0 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2b3b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2b3c0 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2b3d0 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2b3e0 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2b3f0 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2b400 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2b410 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2b420 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2b430 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2b440 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2b450 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2b460 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2b470 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2b480 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2b490 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2b4a0 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2b4b0 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2b4c0 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2b4d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2b4e0 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2b4f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2b500 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2b510 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2b520 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2b530 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2b540 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2b550 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2b560 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2b570 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2b580 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2b590 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2b5a0 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2b5b0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2b5c0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2b5d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2b5e0 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2b5f0 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2b600 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2b610 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2b620 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2b630 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2b640 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2b650 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2b660 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2b670 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2b680 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2b690 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2b6a0 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79  P) is managed by
2b6b0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a   SQLite and is.*
2b6c0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2b6d0 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2b6e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b6f0 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2b700 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2b710 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b720 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b730 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2b740 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2b750 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2b760 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2b770 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2b780 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2b790 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2b7a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2b7b0 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ree()]..*/.const
2b7c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
2b7d0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2b7e0 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73  *pStmt);.char *s
2b7f0 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b800 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2b810 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2b820 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2b830 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
2b840 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
2b850 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
2b860 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b870 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2b880 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2b890 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
2b8a0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2b8b0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
2b8c0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
2b8d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b8e0 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
2b8f0 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
2b900 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
2b910 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2b920 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
2b930 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
2b940 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2b950 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
2b960 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2b970 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
2b980 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
2b990 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
2b9a0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
2b9b0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2b9c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2b9d0 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
2b9e0 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
2b9f0 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
2ba00 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
2ba10 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2ba20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
2ba30 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
2ba40 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2ba50 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
2ba60 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
2ba70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
2ba80 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
2ba90 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
2baa0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
2bab0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2bac0 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
2bad0 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
2bae0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2baf0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
2bb00 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
2bb10 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
2bb20 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2bb30 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
2bb40 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
2bb50 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
2bb60 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
2bb70 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
2bb80 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
2bb90 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
2bba0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
2bbb0 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
2bbc0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2bbd0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2bbe0 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
2bbf0 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
2bc00 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
2bc10 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
2bc20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
2bc30 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
2bc40 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
2bc50 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
2bc60 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
2bc70 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
2bc80 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
2bc90 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
2bca0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
2bcb0 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
2bcc0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2bcd0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2bce0 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2bcf0 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2bd00 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2bd10 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2bd20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bd30 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2bd40 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2bd50 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2bd60 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2bd70 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2bd80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bd90 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2bda0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2bdb0 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49  s true for [BEGI
2bdc0 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47  N] since.** [BEG
2bdd0 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20  IN] merely sets 
2bde0 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20  internal flags, 
2bdf0 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42  but the [BEGIN|B
2be00 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20  EGIN IMMEDIATE] 
2be10 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45  and.** [BEGIN|BE
2be20 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63  GIN EXCLUSIVE] c
2be30 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68  ommands do touch
2be40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
2be50 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d so.** sqlite3_
2be60 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2be70 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f  returns false fo
2be80 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73  r those commands
2be90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2bea0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
2beb0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2bec0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2bed0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2bee0 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
2bef0 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
2bf00 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
2bf10 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2bf20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bf30 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2bf40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bf50 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2bf60 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2bf70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bf80 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2bf90 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2bfa0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2bfb0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2bfc0 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e   has neither run
2bfd0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28   to completion (
2bfe0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2bff0 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b  ITE_DONE] from [
2c000 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2c010 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65  ) nor.** been re
2c020 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
2c030 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
2c040 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2c050 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
2c060 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
2c070 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
2c080 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
2c090 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
2c0a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
2c0b0 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
2c0c0 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
2c0d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c0e0 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
2c0f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2c100 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2c110 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
2c120 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
2c130 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2c140 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
2c150 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
2c160 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
2c170 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
2c180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
2c190 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2c1a0 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
2c1b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
2c1c0 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
2c1d0 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
2c1e0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
2c1f0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
2c200 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
2c210 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
2c220 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
2c230 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
2c240 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
2c250 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
2c260 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2c270 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2c280 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2c290 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2c2a0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2c2b0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2c2c0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2c2d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2c2e0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2c2f0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2c300 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2c310 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2c320 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2c330 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2c340 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2c350 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2c360 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2c370 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2c380 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2c390 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2c3a0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2c3b0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2c3c0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2c3d0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2c3e0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2c3f0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2c400 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2c410 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2c420 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2c430 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2c440 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2c450 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2c460 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2c470 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2c480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2c490 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2c4a0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2c4b0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2c4c0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2c4d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c4e0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2c4f0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2c500 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2c510 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2c520 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2c530 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2c540 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2c550 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2c560 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2c570 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
2c580 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2c590 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
2c5a0 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
2c5b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c5c0 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
2c5d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c5e0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
2c5f0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
2c600 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
2c610 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
2c620 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
2c630 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
2c640 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
2c650 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
2c660 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c670 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c680 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
2c690 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
2c6a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c6b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c6c0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
2c6d0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
2c6e0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
2c6f0 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
2c700 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
2c710 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
2c720 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
2c730 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
2c740 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
2c750 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
2c760 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
2c770 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
2c780 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2c790 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
2c7a0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2c7b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
2c7c0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
2c7d0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2c7e0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2c7f0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2c800 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
2c810 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
2c820 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
2c830 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
2c840 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
2c850 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
2c860 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
2c870 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
2c880 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
2c890 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
2c8a0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2c8b0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2c8c0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c8d0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
2c8e0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
2c8f0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2c900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2c910 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
2c920 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
2c930 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
2c940 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
2c950 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
2c960 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2c970 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
2c980 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
2c990 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2c9a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2c9b0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2c9c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2c9d0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
2c9e0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
2c9f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ca00 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
2ca10 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
2ca20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2ca30 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2ca40 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2ca50 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2ca60 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
2ca70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2ca80 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
2ca90 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
2caa0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
2cab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2cac0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
2cad0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
2cae0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2caf0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2cb00 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2cb10 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2cb20 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2cb30 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2cb40 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2cb50 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2cb60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2cb70 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2cb80 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2cb90 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2cba0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2cbb0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2cbc0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2cbd0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2cbe0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2cbf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2cc00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2cc10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2cc20 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2cc30 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2cc40 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2cc50 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2cc60 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2cc70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2cc80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2cc90 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2cca0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2ccb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2ccc0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2ccd0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2cce0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2ccf0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2cd00 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2cd10 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2cd20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2cd30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2cd40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cd50 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2cd60 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2cd70 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2cd80 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2cd90 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2cda0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2cdb0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2cdc0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2cdd0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2cde0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2cdf0 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2ce00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ce10 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2ce20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ce30 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2ce40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ce50 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2ce60 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2ce70 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2ce80 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2ce90 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2cea0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2ceb0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2cec0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2ced0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2cee0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2cef0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2cf00 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2cf10 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2cf20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2cf30 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2cf40 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2cf50 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2cf60 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2cf70 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2cf80 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2cf90 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2cfa0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2cfb0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2cfc0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2cfd0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2cfe0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2cff0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2d000 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2d010 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2d020 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2d030 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2d040 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2d050 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2d060 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2d070 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2d080 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2d090 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2d0a0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2d0b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d0c0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2d0d0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2d0e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2d0f0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2d100 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2d110 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2d120 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2d130 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2d140 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2d150 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2d160 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2d170 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2d180 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2d190 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2d1a0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2d1b0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2d1c0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2d1d0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2d1e0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2d1f0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2d200 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2d210 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2d220 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d230 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2d240 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2d250 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2d260 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2d270 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2d280 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2d290 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2d2a0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2d2b0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2d2c0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2d2d0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2d2e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2d2f0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2d300 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2d310 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2d320 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2d330 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2d340 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2d350 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2d360 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2d370 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2d380 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2d390 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2d3a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2d3b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2d3c0 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2d3d0 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2d3e0 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2d3f0 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2d400 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2d410 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2d420 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2d430 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2d440 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2d450 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2d460 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2d470 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d480 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2d490 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2d4a0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2d4b0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2d4c0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2d4d0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2d4e0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2d4f0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2d500 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d510 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2d520 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2d530 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d540 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2d550 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2d560 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2d570 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2d580 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2d590 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2d5a0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2d5b0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2d5c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2d5d0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2d5e0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2d5f0 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2d600 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2d610 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2d620 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d630 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2d640 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d650 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2d660 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d670 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2d680 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2d690 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2d6a0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2d6b0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2d6c0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2d6d0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2d6e0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2d6f0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2d700 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2d710 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2d720 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2d730 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2d740 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2d750 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2d760 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2d770 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2d780 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2d790 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2d7a0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2d7b0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2d7c0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2d7d0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2d7e0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2d7f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2d800 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2d810 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2d820 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2d830 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2d840 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2d850 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2d860 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2d870 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2d880 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2d890 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2d8a0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2d8b0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2d8c0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2d8d0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2d8e0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2d8f0 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2d900 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2d910 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2d920 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2d930 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2d940 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2d950 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2d960 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2d970 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2d980 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2d990 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2d9a0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2d9b0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2d9c0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2d9d0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2d9e0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2d9f0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2da00 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2da10 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2da20 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2da30 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2da40 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2da50 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2da60 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2da70 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2da80 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2da90 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2daa0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2dab0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2dac0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2dad0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2dae0 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2daf0 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2db00 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2db10 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2db20 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2db30 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2db40 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2db50 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2db60 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2db70 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2db80 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2db90 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2dba0 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2dbb0 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2dbc0 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2dbd0 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2dbe0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2dbf0 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2dc00 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2dc10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2dc20 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2dc30 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2dc40 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2dc50 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2dc60 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2dc70 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2dc80 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2dc90 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2dca0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2dcb0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2dcc0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2dcd0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2dce0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2dcf0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2dd00 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2dd10 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2dd20 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2dd30 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2dd40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2dd50 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2dd60 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2dd70 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2dd80 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2dd90 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2dda0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2ddb0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2ddc0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2ddd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2dde0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2ddf0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2de00 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2de10 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2de20 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2de30 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2de40 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2de50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2de60 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2de70 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2de80 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2de90 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2dea0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2deb0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2dec0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2ded0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2dee0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2def0 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2df00 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2df10 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2df20 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2df30 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2df40 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2df50 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2df60 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2df70 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2df80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2df90 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2dfa0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2dfb0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2dfc0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2dfd0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2dfe0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2dff0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2e000 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2e010 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2e020 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2e030 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2e040 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2e050 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2e060 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2e070 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2e080 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2e090 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2e0a0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2e0b0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2e0c0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2e0d0 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2e0e0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2e0f0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2e100 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2e110 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2e120 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2e130 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2e140 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2e150 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2e160 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e170 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2e180 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2e190 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e1a0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2e1b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e1c0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e1d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e1e0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2e1f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e200 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2e210 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2e220 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2e230 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(sqli
2e240 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e250 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c  const void*, sql
2e260 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2e270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e280 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2e290 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2e2a0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2e2b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e2c0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
2e2d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
2e2e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e2f0 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
2e300 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2e310 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e320 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2e330 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
2e340 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2e350 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2e360 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e370 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2e380 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2e390 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2e3a0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2e3b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2e3c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e3d0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2e3e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2e3f0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2e400 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2e410 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e420 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2e430 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2e440 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2e450 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2e460 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2e470 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2e480 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e490 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
2e4a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e4b0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2e4c0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e4d0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2e4e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e4f0 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73  t, int n);.int s
2e500 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2e510 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2e520 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2e530 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  e3_uint64);../*.
2e540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2e550 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2e560 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
2e570 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e580 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2e590 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2e5a0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2e5b0 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2e5c0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2e5d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e5e0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2e5f0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2e600 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2e610 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2e620 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2e630 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2e640 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2e650 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2e660 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2e670 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2e680 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2e690 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2e6a0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2e6b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2e6c0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2e6d0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2e6e0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2e6f0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2e700 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2e710 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2e720 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2e730 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2e740 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2e750 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2e760 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2e770 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2e780 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2e790 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2e7a0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2e7b0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e7c0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2e7d0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2e7e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e7f0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2e800 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2e810 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2e820 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2e830 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e840 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2e850 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2e860 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2e870 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2e880 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eter.** METHOD: 
2e890 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e8a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e8b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2e8c0 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
2e8d0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
2e8e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
2e8f0 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
2e900 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
2e910 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2e920 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
2e930 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2e940 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
2e950 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2e960 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
2e970 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
2e980 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
2e990 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2e9a0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2e9b0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
2e9c0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2e9d0 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
2e9e0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
2e9f0 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
2ea00 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
2ea10 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
2ea20 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
2ea30 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
2ea40 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
2ea50 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
2ea60 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
2ea70 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
2ea80 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
2ea90 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
2eaa0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
2eab0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
2eac0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2ead0 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
2eae0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
2eaf0 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
2eb00 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
2eb10 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
2eb20 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
2eb30 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
2eb40 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
2eb50 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
2eb60 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
2eb70 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
2eb80 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
2eb90 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
2eba0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
2ebb0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2ebc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ebd0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
2ebe0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ebf0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2ec00 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2ec10 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2ec20 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2ec30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ec40 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2ec50 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2ec60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2ec70 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
2ec80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
2ec90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2eca0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2ecb0 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
2ecc0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
2ecd0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
2ece0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
2ecf0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ed00 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2ed10 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2ed20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2ed30 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2ed40 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2ed50 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2ed60 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2ed70 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2ed80 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2ed90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2eda0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2edb0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2edc0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2edd0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2ede0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2edf0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2ee00 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2ee10 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2ee20 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2ee30 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2ee40 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2ee50 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2ee60 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2ee70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ee80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2ee90 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2eea0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2eeb0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2eec0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2eed0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2eee0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2eef0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2ef00 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2ef10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ef20 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2ef30 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2ef40 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2ef50 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2ef60 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2ef70 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2ef80 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2ef90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2efa0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2efb0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2efc0 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2efd0 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2efe0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2eff0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f000 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2f010 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2f020 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2f030 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2f040 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2f050 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2f060 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
2f070 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2f080 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2f090 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f0a0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2f0b0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2f0c0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2f0d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f0e0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2f0f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2f100 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2f110 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2f120 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2f130 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66   statement]. ^If
2f140 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
2f150 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65  turns 0, that me
2f160 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  ans the .** [pre
2f170 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f180 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61   returns no data
2f190 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2f1a0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e   [UPDATE])..** ^
2f1b0 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65  However, just be
2f1c0 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  cause this routi
2f1d0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ne returns a pos
2f1e0 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65  itive number doe
2f1f0 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68  s not.** mean th
2f200 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72  at one or more r
2f210 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c  ows of data will
2f220 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   be returned.  ^
2f230 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  A SELECT stateme
2f240 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79  nt.** will alway
2f250 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76  s have a positiv
2f260 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f270 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70  _count() but dep
2f280 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a  ending on the.**
2f290 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
2f2a0 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
2f2b0 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c  e table content,
2f2c0 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e   it might return
2f2d0 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20   no rows..**.** 
2f2e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f2f0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2f300 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f310 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2f320 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f330 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f340 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2f350 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2f360 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f370 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f380 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2f390 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2f3a0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2f3b0 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2f3c0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2f3d0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2f3e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2f3f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2f400 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2f410 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f420 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2f430 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2f440 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2f450 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f460 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2f470 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2f480 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2f490 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2f4a0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2f4b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2f4c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f4d0 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2f4e0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2f4f0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2f500 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2f510 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2f520 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2f530 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2f540 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2f550 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2f560 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2f570 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2f580 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2f590 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f5a0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2f5b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2f5c0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2f5d0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2f5e0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2f5f0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2f600 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2f610 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2f620 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2f630 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2f640 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2f650 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2f660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2f670 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2f680 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2f690 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2f6a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2f6b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2f6c0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2f6d0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2f6e0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2f6f0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2f700 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2f710 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2f720 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2f730 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2f740 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2f750 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2f760 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2f770 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2f780 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2f790 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2f7a0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2f7b0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2f7c0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2f7d0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2f7e0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2f7f0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2f800 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2f810 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2f820 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2f830 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
2f840 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2f850 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2f860 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f870 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
2f880 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f890 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2f8a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2f8b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2f8c0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2f8d0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2f8e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f8f0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2f900 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2f910 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2f920 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2f930 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2f940 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2f950 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2f960 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2f970 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2f980 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2f990 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2f9a0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2f9b0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2f9c0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2f9d0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2f9e0 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2f9f0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2fa00 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2fa10 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2fa20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2fa30 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2fa40 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2fa50 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2fa60 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2fa70 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2fa80 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2fa90 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2faa0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2fab0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2fac0 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2fad0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2fae0 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2faf0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2fb00 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2fb10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2fb20 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2fb30 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2fb40 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2fb50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2fb60 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2fb70 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2fb80 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2fb90 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2fba0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2fbb0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2fbc0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2fbd0 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2fbe0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2fbf0 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2fc00 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2fc10 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2fc20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2fc30 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2fc40 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2fc50 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2fc60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fc70 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2fc80 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2fc90 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2fca0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2fcb0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2fcc0 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2fcd0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2fce0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2fcf0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2fd00 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2fd10 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2fd20 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2fd30 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2fd40 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2fd50 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2fd60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2fd70 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2fd80 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2fd90 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2fda0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2fdb0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2fdc0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2fdd0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2fde0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2fdf0 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2fe00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2fe10 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2fe20 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2fe30 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2fe40 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2fe50 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2fe60 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2fe70 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2fe80 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2fe90 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2fea0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2feb0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2fec0 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2fed0 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2fee0 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2fef0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2ff00 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2ff10 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2ff20 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2ff30 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2ff40 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2ff50 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2ff60 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2ff70 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2ff80 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2ff90 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2ffa0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2ffb0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2ffc0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2ffd0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2ffe0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2fff0 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
30000 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
30010 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
30020 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
30030 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
30040 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
30050 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
30060 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
30070 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
30080 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
30090 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
300a0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
300b0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
300c0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
300d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
300e0 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
300f0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
30100 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
30110 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
30120 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
30130 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
30140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
30150 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
30160 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
30170 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30180 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
30190 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
301a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
301b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
301c0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
301d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
301e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
301f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30200 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
30210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
30220 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
30230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
30240 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
30250 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
30260 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30270 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
30280 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
30290 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
302a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
302b0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
302c0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
302d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
302e0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
302f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
30300 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
30310 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
30320 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
30330 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
30340 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
30350 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
30360 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
30370 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
30380 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
30390 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
303a0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
303b0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
303c0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
303d0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
303e0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
303f0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
30400 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
30410 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
30420 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
30430 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
30440 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
30450 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
30460 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
30470 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
30480 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
30490 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
304a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
304b0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
304c0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
304d0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
304e0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
304f0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
30500 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
30510 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
30520 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
30530 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
30540 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
30550 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
30560 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
30570 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
30580 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
30590 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
305a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
305b0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
305c0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
305d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
305e0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
305f0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
30600 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
30610 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
30620 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
30630 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
30640 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
30650 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
30660 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
30670 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
30680 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
30690 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
306a0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
306b0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
306c0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
306d0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
306e0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
306f0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
30700 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
30710 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
30720 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
30730 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
30740 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
30750 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
30760 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
30770 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
30780 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30790 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
307a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
307b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
307c0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
307d0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
307e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
307f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74  3_stmt.**.** Aft
30800 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
30810 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
30820 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
30830 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
30840 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30850 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
30860 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
30870 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
30880 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
30890 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
308a0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
308b0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
308c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
308d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
308e0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
308f0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
30900 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
30910 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
30920 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
30930 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
30940 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
30950 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
30960 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
30970 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
30980 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
30990 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
309a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
309b0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
309c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
309d0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
309e0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
309f0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
30a00 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
30a10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30a20 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
30a30 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
30a40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
30a50 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
30a60 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
30a70 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
30a80 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
30a90 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
30aa0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
30ab0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
30ac0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
30ad0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
30ae0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
30af0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
30b00 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
30b10 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
30b20 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
30b30 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
30b40 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
30b50 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
30b60 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
30b70 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
30b80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
30b90 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
30ba0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
30bb0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
30bc0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
30bd0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
30be0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
30bf0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
30c00 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
30c10 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
30c20 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
30c30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
30c40 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
30c50 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
30c60 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
30c70 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
30c80 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
30c90 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
30ca0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
30cb0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
30cc0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
30cd0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
30ce0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30cf0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
30d00 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
30d10 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
30d20 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
30d30 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
30d40 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
30d50 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
30d60 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
30d70 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
30d80 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
30d90 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
30da0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
30db0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
30dc0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
30dd0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
30de0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
30df0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
30e00 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
30e10 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
30e20 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
30e30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
30e40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
30e50 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
30e60 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
30e70 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
30e80 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
30e90 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
30ea0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
30eb0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
30ec0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
30ed0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
30ee0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
30ef0 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
30f00 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
30f10 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
30f20 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
30f30 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
30f40 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
30f50 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
30f60 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
30f70 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
30f80 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
30f90 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
30fa0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
30fb0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
30fc0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
30fd0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
30fe0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
30ff0 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
31000 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
31010 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
31020 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
31030 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
31040 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
31050 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
31060 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
31070 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
31080 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
31090 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
310a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
310b0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
310c0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
310d0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
310e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
310f0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
31100 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31110 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
31120 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
31130 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
31140 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
31150 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
31160 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
31170 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
31180 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
31190 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
311a0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
311b0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
311c0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
311d0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
311e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
311f0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
31200 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
31210 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
31220 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
31230 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
31240 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
31250 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
31260 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
31270 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
31280 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
31290 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
312a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
312b0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
312c0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
312d0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
312e0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
312f0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
31300 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
31310 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
31320 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
31330 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
31340 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
31350 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
31360 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
31370 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
31380 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
31390 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
313a0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
313b0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
313c0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
313d0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
313e0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
313f0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
31400 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
31410 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31420 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
31430 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
31440 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
31450 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
31460 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
31470 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e  [version 3.6.23.
31480 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  1] ([dateof:3.6.
31490 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65  23.1],.** sqlite
314a0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
314b0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
314c0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
314d0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
314e0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
314f0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
31500 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
31510 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
31520 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
31530 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
31540 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
31550 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
31560 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
31570 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
31580 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
31590 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
315a0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
315b0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
315c0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
315d0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
315e0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
315f0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
31600 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
31610 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
31620 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
31630 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
31640 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
31650 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
31660 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
31670 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
31680 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
31690 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
316a0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
316b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
316c0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
316d0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
316e0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
316f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
31700 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31710 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
31720 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
31730 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
31740 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
31750 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
31760 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
31770 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
31780 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
31790 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
317a0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
317b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
317c0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
317d0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
317e0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
317f0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
31800 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
31810 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
31820 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
31830 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
31840 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
31850 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
31860 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
31870 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
31880 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
31890 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
318a0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
318b0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
318c0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
318d0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
318e0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
318f0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
31900 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
31910 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31920 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
31930 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
31940 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
31950 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
31960 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
31970 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31980 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31990 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
319a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
319b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
319c0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
319d0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
319e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
319f0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
31a00 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
31a10 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
31a20 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
31a30 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
31a40 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
31a50 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
31a60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
31a70 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
31a80 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
31a90 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
31aa0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
31ab0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
31ac0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
31ad0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31ae0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
31af0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
31b00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
31b10 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31b20 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
31b30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31b40 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
31b50 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
31b60 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
31b70 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
31b80 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
31b90 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31ba0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
31bb0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
31bc0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
31bd0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
31be0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
31bf0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
31c00 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
31c10 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
31c20 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
31c30 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
31c40 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
31c50 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
31c60 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
31c70 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
31c80 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
31c90 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
31ca0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31cb0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
31cc0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
31cd0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
31ce0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
31cf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31d00 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
31d10 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
31d20 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
31d30 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
31d40 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
31d50 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
31d60 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
31d70 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
31d80 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
31d90 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31da0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
31db0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
31dc0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
31dd0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
31de0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
31df0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
31e00 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
31e10 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
31e20 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
31e30 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
31e40 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
31e50 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
31e60 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
31e70 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
31e80 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
31e90 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
31ea0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
31eb0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
31ec0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
31ed0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
31ee0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
31ef0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
31f00 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
31f10 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
31f20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
31f30 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
31f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
31f50 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
31f60 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
31f70 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
31f80 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
31f90 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
31fa0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
31fb0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
31fc0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
31fd0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
31fe0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
31ff0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
32000 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
32010 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
32020 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
32030 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
32040 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
32050 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
32060 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
32070 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
32080 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
32090 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
320a0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
320b0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
320c0 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
320d0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
320e0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
320f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
32100 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
32110 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
32120 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
32130 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
32140 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
32150 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
32160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
32170 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
32180 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
32190 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
321a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
321b0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
321c0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
321d0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
321e0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
321f0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
32200 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
32210 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
32220 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
32230 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
32240 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
32250 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
32260 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
32270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
32280 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
32290 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
322a0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
322b0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
322c0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
322d0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
322e0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
322f0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
32300 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
32310 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32320 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
32330 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
32340 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
32350 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
32360 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
32370 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
32380 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
32390 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
323a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
323b0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
323c0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
323d0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
323e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
323f0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
32400 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
32410 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
32420 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
32430 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
32440 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
32450 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
32460 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
32470 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
32480 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
32490 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
324a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
324b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
324c0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
324d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
324e0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
324f0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
32500 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
32510 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
32520 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
32530 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
32540 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
32550 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32560 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
32570 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
32580 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
32590 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
325a0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
325b0 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
325c0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
325d0 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
325e0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
325f0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
32600 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
32610 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
32620 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
32630 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
32640 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
32650 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
32660 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
32670 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
32680 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
32690 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
326a0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
326b0 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
326c0 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
326d0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
326e0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
326f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
32700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32710 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
32720 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
32730 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
32740 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
32750 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
32760 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
32770 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
32780 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
32790 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
327a0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
327b0 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
327c0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
327d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
327e0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
327f0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
32800 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
32810 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
32820 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32830 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
32840 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
32850 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32860 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
32870 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
32880 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
32890 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
328a0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
328b0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
328c0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
328d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
328e0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
328f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
32900 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
32910 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
32920 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
32930 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
32940 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32950 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
32960 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
32970 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
32980 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32990 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
329a0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
329b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
329c0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
329d0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
329e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
329f0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
32a00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
32a10 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
32a20 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
32a30 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
32a40 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
32a50 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
32a60 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32a70 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
32a80 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
32a90 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
32aa0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
32ab0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
32ac0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
32ad0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
32ae0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
32af0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32b00 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
32b10 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
32b20 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
32b30 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
32b40 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
32b50 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
32b60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
32b70 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
32b80 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
32b90 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
32ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32bb0 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
32bc0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
32bd0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
32be0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
32bf0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
32c00 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
32c10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
32c20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
32c30 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
32c40 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
32c50 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
32c60 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
32c70 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
32c80 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
32c90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32ca0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32cb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32cc0 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
32cd0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
32ce0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
32cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
32d00 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
32d10 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
32d20 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
32d30 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
32d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32d50 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
32d60 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
32d70 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
32d80 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
32d90 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
32da0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
32db0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
32dc0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
32dd0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
32de0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
32df0 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
32e00 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
32e10 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
32e20 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
32e30 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
32e40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32e50 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
32e60 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
32e70 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
32e80 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
32e90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
32ea0 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
32eb0 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
32ec0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
32ed0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
32ee0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
32ef0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
32f00 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
32f10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32f20 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
32f30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
32f40 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
32f50 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
32f60 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
32f70 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
32f80 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
32f90 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
32fa0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32fb0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
32fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32fd0 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
32fe0 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
32ff0 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
33000 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
33010 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
33020 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
33030 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
33040 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
33050 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
33060 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
33070 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
33080 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
33090 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
330a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
330b0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
330c0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
330d0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
330e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
330f0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
33100 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
33110 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
33120 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
33130 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
33140 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
33150 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
33160 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
33170 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
33180 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
33190 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
331a0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
331b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
331c0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
331d0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
331e0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
331f0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
33200 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
33210 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
33220 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
33230 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
33240 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
33250 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
33260 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
33270 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
33280 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
33290 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
332a0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
332b0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
332c0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
332d0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
332e0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
332f0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
33300 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
33310 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
33320 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
33330 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
33340 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
33350 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
33360 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
33370 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
33380 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
33390 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
333a0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
333b0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
333c0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
333d0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
333e0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
333f0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
33400 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
33410 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
33420 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
33430 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
33440 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
33450 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
33460 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
33470 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
33480 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
33490 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
334a0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
334b0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
334c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
334d0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
334e0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
334f0 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
33500 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
33510 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
33520 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
33530 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
33540 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
33550 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
33560 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
33570 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
33580 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
33590 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
335a0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
335b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
335c0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
335d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
335e0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
335f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33600 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
33610 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
33620 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
33630 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
33640 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
33650 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
33660 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
33670 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
33680 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
33690 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
336a0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
336b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
336c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
336d0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
336e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
336f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
33700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33710 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
33720 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
33730 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
33740 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
33750 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
33760 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
33770 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
33780 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
33790 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
337a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
337b0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
337c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
337d0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
337e0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
337f0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
33800 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
33810 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
33820 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
33830 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
33840 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
33850 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
33860 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
33870 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
33880 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
33890 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
338a0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
338b0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
338c0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
338d0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
338e0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
338f0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
33900 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
33910 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
33920 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
33930 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
33940 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
33950 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
33960 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
33970 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
33980 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
33990 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
339a0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
339b0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
339c0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
339d0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
339e0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
339f0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
33a00 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
33a10 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
33a20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
33a30 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
33a40 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
33a50 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
33a60 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
33a70 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
33a80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
33a90 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
33aa0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
33ab0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
33ac0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
33ad0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
33ae0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
33af0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33b00 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
33b10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33b20 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
33b30 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
33b40 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
33b50 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
33b60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33b70 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
33b80 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
33b90 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
33ba0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
33bb0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
33bc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33bd0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
33be0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33bf0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
33c00 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
33c10 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
33c20 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
33c30 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
33c40 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
33c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33c60 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
33c70 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
33c80 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
33c90 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
33ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33cb0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
33cc0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
33cd0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
33ce0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33cf0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
33d00 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
33d10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
33d20 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
33d30 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
33d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33d50 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
33d60 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
33d70 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
33d80 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
33d90 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
33da0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
33db0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
33dc0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
33dd0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
33de0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
33df0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
33e00 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
33e10 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
33e20 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
33e30 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
33e40 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
33e50 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
33e60 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
33e70 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
33e80 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
33e90 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
33ea0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33eb0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
33ec0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
33ed0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
33ee0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
33ef0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
33f00 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
33f10 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
33f20 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
33f30 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
33f40 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
33f50 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
33f60 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
33f70 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
33f80 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
33f90 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
33fa0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
33fb0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
33fc0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
33fd0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
33fe0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
33ff0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
34000 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
34010 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
34020 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
34030 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
34040 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
34050 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
34060 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34070 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
34080 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
34090 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
340a0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
340b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
340c0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
340d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
340e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
340f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
34100 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
34110 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
34120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
34130 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
34140 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
34150 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
34160 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
34170 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
34180 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
34190 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
341a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
341b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
341c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
341d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
341e0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
341f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
34200 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
34210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
34220 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
34230 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
34240 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
34250 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
34260 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
34270 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
34280 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
34290 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
342a0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
342b0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
342c0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
342d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
342e0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
342f0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
34300 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
34310 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
34320 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
34330 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
34340 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
34350 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
34360 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
34370 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
34380 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
34390 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
343a0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
343b0 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
343c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
343d0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
343e0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
343f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
34400 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
34410 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
34420 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
34430 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
34440 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
34450 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
34460 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
34470 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
34480 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
34490 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
344a0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
344b0 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
344c0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
344d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
344e0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
344f0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
34500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
34510 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
34520 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
34530 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
34540 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
34550 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
34560 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
34570 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
34580 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34590 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
345a0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
345b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
345c0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
345d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
345e0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
345f0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
34600 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
34610 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
34620 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
34630 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
34640 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
34650 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
34660 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
34670 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
34680 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
34690 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
346a0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
346b0 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
346c0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
346d0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
346e0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
346f0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
34700 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
34710 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
34720 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
34730 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
34740 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34750 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
34760 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
34770 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
34780 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
34790 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
347a0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
347b0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
347c0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
347d0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
347e0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
347f0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
34800 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
34810 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
34820 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
34830 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
34840 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
34850 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
34860 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
34870 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
34880 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
34890 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
348a0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
348b0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
348c0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
348d0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
348e0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
348f0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
34900 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
34910 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34920 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
34930 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
34940 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
34950 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
34960 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
34970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
34980 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
34990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
349a0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
349b0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
349c0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
349d0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
349e0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
349f0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
34a00 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
34a10 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
34a20 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
34a30 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
34a40 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
34a50 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
34a60 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
34a70 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
34a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
34a90 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
34aa0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
34ab0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
34ac0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
34ad0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
34ae0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
34af0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
34b00 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
34b10 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
34b20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
34b30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
34b40 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
34b50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34b60 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
34b70 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
34b80 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
34b90 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
34ba0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
34bb0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
34bc0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
34bd0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
34be0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34bf0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
34c00 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34c10 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34c20 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
34c30 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34c40 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34c50 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
34c60 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
34c70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
34c80 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
34c90 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
34ca0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
34cb0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
34cc0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
34cd0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34ce0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
34cf0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
34d00 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
34d10 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
34d20 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
34d30 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
34d40 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
34d50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
34d60 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
34d70 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
34d80 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
34d90 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
34da0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
34db0 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
34dc0 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
34dd0 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
34de0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
34df0 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
34e00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
34e10 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
34e20 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
34e30 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
34e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34e50 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
34e60 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
34e70 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
34e80 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
34e90 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
34ea0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
34eb0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
34ec0 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
34ed0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
34ee0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
34ef0 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
34f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34f10 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
34f20 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
34f30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
34f40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
34f50 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
34f60 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
34f70 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
34f80 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
34f90 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
34fa0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
34fb0 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
34fc0 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
34fd0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
34fe0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
34ff0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
35000 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
35010 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
35020 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
35030 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
35040 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
35050 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
35060 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
35070 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
35080 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
35090 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
350a0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
350b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
350c0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
350d0 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
350e0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
350f0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
35100 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
35110 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
35120 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
35130 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
35140 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
35150 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
35160 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
35170 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
35180 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
35190 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
351a0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
351b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
351c0 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
351d0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
351e0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
351f0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
35200 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
35210 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
35220 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
35230 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
35240 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
35250 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
35260 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
35270 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
35280 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
35290 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
352a0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
352b0 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
352c0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
352d0 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
352e0 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
352f0 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
35300 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35310 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
35320 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
35330 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
35340 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
35350 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35360 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
35370 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
35380 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
35390 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
353a0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
353b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
353c0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
353d0 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
353e0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
353f0 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
35400 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
35410 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
35420 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
35430 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
35440 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
35450 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35460 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
35470 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
35480 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
35490 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
354a0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
354b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
354c0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
354d0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
354e0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
354f0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
35500 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
35510 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
35520 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
35530 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
35540 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
35550 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
35560 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
35570 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
35580 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
35590 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
355a0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
355b0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
355c0 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
355d0 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
355e0 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
355f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
35600 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
35610 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
35620 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
35630 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
35640 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
35650 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
35660 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
35670 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
35680 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
35690 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
356a0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
356b0 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
356c0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
356d0 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
356e0 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
356f0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
35700 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
35710 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
35720 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
35730 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
35740 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
35750 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
35760 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
35770 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35780 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
35790 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
357a0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
357b0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
357c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
357d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
357e0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
357f0 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
35800 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
35810 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
35820 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
35830 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
35840 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
35850 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
35860 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
35870 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
35880 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
35890 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
358a0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
358b0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
358c0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
358d0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
358e0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
358f0 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
35900 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
35910 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
35920 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
35930 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35940 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
35950 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
35960 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
35970 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
35980 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
35990 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
359a0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
359b0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
359c0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
359d0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
359e0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
359f0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
35a00 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
35a10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35a20 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
35a30 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
35a40 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
35a50 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
35a60 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
35a70 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
35a80 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
35a90 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
35aa0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
35ab0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
35ac0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
35ad0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
35ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35af0 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
35b00 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
35b10 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
35b20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
35b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35b40 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
35b50 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
35b60 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
35b70 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
35b80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
35b90 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
35ba0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
35bb0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
35bc0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35bd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
35be0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
35bf0 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
35c00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
35c10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35c20 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
35c30 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
35c40 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
35c50 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
35c60 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
35c70 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
35c80 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
35c90 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
35ca0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
35cb0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
35cc0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
35cd0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
35ce0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
35cf0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
35d00 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
35d10 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
35d20 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
35d30 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
35d40 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
35d50 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
35d60 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35d70 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
35d80 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
35d90 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
35da0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
35db0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
35dc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35dd0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
35de0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
35df0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
35e00 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
35e10 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
35e20 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
35e30 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
35e40 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
35e50 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
35e60 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
35e70 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
35e80 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
35e90 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
35ea0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
35eb0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
35ec0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
35ed0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
35ee0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
35ef0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
35f00 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
35f10 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
35f20 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
35f30 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
35f40 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
35f50 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
35f60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35f70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
35f80 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
35f90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35fa0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
35fb0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
35fc0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
35fd0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
35fe0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
35ff0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
36000 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
36010 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
36020 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
36030 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
36040 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
36050 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
36060 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
36070 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36080 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
36090 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
360a0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
360b0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
360c0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
360d0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
360e0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
360f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36100 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36110 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36120 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
36130 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
36140 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
36150 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
36160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
36170 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
36180 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
36190 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
361a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
361b0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
361c0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
361d0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
361e0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
361f0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
36200 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36210 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36220 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
36230 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36240 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
36250 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
36260 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
36270 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
36280 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
36290 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
362a0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
362b0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
362c0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
362d0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
362e0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
362f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
36300 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
36310 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
36320 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
36330 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
36340 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
36350 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
36360 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
36370 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36380 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
36390 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
363a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
363b0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
363c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
363d0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
363e0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
363f0 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
36400 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
36410 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
36420 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
36430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
36440 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
36450 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
36460 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
36470 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
36480 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
36490 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
364a0 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
364b0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
364c0 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
364d0 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
364e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
364f0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
36500 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
36510 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
36520 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36530 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
36540 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
36550 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
36560 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36570 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
36580 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36590 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
365a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
365b0 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
365c0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
365d0 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
365e0 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
365f0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
36600 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
36610 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
36620 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
36630 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
36640 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36650 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
36660 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36670 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
36680 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36690 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
366a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
366b0 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
366c0 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
366d0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
366e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
366f0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
36700 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
36710 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
36720 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
36730 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
36740 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
36750 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
36760 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
36770 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
36780 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
36790 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
367a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
367b0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
367c0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
367d0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
367e0 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
367f0 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
36800 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
36810 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
36820 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
36830 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
36840 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
36850 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
36860 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
36870 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
36880 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36890 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
368a0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
368b0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
368c0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
368d0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
368e0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
368f0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
36900 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
36910 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
36920 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36930 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
36940 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
36950 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
36960 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
36970 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
36980 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
36990 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
369a0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
369b0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
369c0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
369d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
369e0 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
369f0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
36a00 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
36a10 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
36a20 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
36a30 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
36a40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
36a50 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
36a60 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
36a70 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
36a80 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
36a90 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
36aa0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
36ab0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
36ac0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
36ad0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
36ae0 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a   aggregate.  .**
36af0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
36b00 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
36b10 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
36b20 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
36b30 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
36b40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36b50 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
36b60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36b70 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
36b80 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
36b90 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
36ba0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36bb0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
36bc0 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
36bd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
36be0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
36bf0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
36c00 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
36c10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36c20 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
36c30 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
36c40 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36c50 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
36c60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
36c70 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
36c80 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
36c90 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
36ca0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
36cb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
36cc0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
36cd0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36ce0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
36cf0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36d00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36d10 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
36d20 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
36d30 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
36d40 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36d50 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
36d60 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
36d70 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
36d80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
36d90 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
36da0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
36db0 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
36dc0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
36dd0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
36de0 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
36df0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
36e00 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36e10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36e20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
36e30 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
36e40 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
36e50 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
36e60 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
36e70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36e80 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
36e90 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
36ea0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
36eb0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
36ec0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
36ed0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
36ee0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
36ef0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36f00 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
36f10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
36f20 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
36f30 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
36f40 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
36f50 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
36f60 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
36f70 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
36f80 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36f90 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
36fa0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
36fb0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
36fc0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
36fd0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
36fe0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
36ff0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
37000 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
37010 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
37020 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
37030 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
37040 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
37050 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
37060 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
37070 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
37080 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
37090 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
370a0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
370b0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
370c0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
370d0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
370e0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
370f0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
37100 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
37110 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
37120 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
37130 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
37140 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
37150 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
37160 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
37170 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
37180 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
37190 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
371a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
371b0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
371c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
371d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
371e0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
371f0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
37200 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
37210 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
37220 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
37230 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
37240 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
37250 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37260 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
37270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37280 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
37290 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
372a0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
372b0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
372c0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
372d0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
372e0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
372f0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
37300 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
37310 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
37320 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
37330 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
37340 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
37350 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
37360 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37370 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
37380 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
37390 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
373a0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
373b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
373c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
373d0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
373e0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
373f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
37400 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
37410 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
37420 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
37430 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
37440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
37450 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37460 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
37470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37480 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
37490 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
374a0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
374b0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
374c0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
374d0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
374e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
374f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
37500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
37520 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
37530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37550 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75  : Finding The Su
37560 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c  btype Of SQL Val
37570 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
37580 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
37590 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
375a0 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20  alue_subtype(V) 
375b0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
375c0 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
375d0 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74  .** an [applicat
375e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
375f0 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65  function] argume
37600 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79  nt V.  The subty
37610 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  pe.** informatio
37620 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
37630 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20   pass a limited 
37640 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78  amount of contex
37650 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51  t from.** one SQ
37660 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e  L function to an
37670 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20  other.  Use the 
37680 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
37690 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f  subtype()].** ro
376a0 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65  utine to set the
376b0 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65   subtype for the
376c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
376d0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
376e0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
376f0 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73  akes no use of s
37700 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20  ubtype itself.  
37710 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73  It merely passes
37720 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   the subtype.** 
37730 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20  from the result 
37740 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74  of one [applicat
37750 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
37760 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74  function] into t
37770 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61  he.** input of a
37780 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67  nother..*/.unsig
37790 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  ned int sqlite3_
377a0 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71  value_subtype(sq
377b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
377c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
377d0 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
377e0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
377f0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
37800 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
37810 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
37820 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
37830 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37840 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
37850 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
37860 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37870 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
37880 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
37890 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
378a0 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
378b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
378c0 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
378d0 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
378e0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
378f0 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
37900 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37910 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
37920 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
37930 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
37940 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
37950 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37960 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
37970 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
37980 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37990 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
379a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
379b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
379c0 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61  ()].  ^If V is a
379d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
379e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61   then sqlite3_va
379f0 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61  lue_free(V) is a
37a00 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
37a10 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  .*/.sqlite3_valu
37a20 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e *sqlite3_value
37a30 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74  _dup(const sqlit
37a40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
37a50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
37a60 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ree(sqlite3_valu
37a70 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
37a80 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
37a90 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
37aa0 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f  Context.** METHO
37ab0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
37ac0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
37ad0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
37ae0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
37af0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
37b00 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
37b10 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
37b20 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
37b30 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
37b40 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
37b50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37b60 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
37b70 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
37b80 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
37b90 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
37ba0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
37bb0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
37bc0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
37bd0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
37be0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
37bf0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
37c00 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
37c10 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
37c20 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
37c30 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
37c40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
37c50 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
37c60 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
37c70 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
37c80 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
37c90 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
37ca0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
37cb0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
37cc0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
37cd0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
37ce0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
37cf0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
37d00 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
37d10 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
37d20 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
37d30 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
37d40 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
37d50 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
37d60 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
37d70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
37d80 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
37d90 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
37da0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
37db0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
37dc0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
37dd0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
37de0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
37df0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37e00 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
37e10 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
37e20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
37e30 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
37e40 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
37e50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
37e60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37e70 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
37e80 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
37e90 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
37ea0 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
37eb0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
37ec0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
37ed0 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
37ee0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
37ef0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
37f00 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
37f10 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
37f20 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37f30 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
37f40 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
37f50 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
37f60 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
37f70 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
37f80 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
37f90 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
37fa0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
37fb0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37fc0 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
37fd0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
37fe0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
37ff0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
38000 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
38010 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
38020 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
38030 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
38040 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
38050 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
38060 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
38070 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
38080 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
38090 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
380a0 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
380b0 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
380c0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
380d0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
380e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
380f0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
38100 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
38110 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
38120 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
38130 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
38140 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
38150 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
38160 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
38170 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
38180 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
38190 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
381a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
381b0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
381c0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
381d0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
381e0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
381f0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
38200 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
38210 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
38220 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
38230 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
38240 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
38250 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
38260 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
38270 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
38280 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
38290 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
382a0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
382b0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
382c0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
382d0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
382e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
382f0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
38300 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
38310 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
38320 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
38330 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
38340 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
38350 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
38360 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
38370 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
38380 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
38390 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
383a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
383b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
383c0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
383d0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
383e0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
383f0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
38400 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
38410 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
38420 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
38430 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
38440 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
38450 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
38460 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
38470 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
38480 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
38490 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
384a0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
384b0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
384c0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
384d0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
384e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
384f0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
38500 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
38510 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
38520 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38530 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
38540 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
38550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38560 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
38570 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
38580 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
38590 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
385a0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
385b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
385c0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
385d0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
385e0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
385f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
38600 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
38610 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
38620 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
38630 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
38640 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
38650 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
38660 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
38670 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
38680 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
38690 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
386a0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
386b0 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
386c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
386d0 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
386e0 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
386f0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
38700 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
38710 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
38720 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
38730 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
38740 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
38750 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
38760 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
38770 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
38780 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
38790 20 6d 65 7